pluresdb 1.0.1

package/scripts/setup-libclang.ps1

@@ -0,0 +1,209 @@
+<#
+.SYNOPSIS
+    Ensures libclang (LLVM) is installed and configures the LIBCLANG_PATH required by bindgen-based crates.
+
+.DESCRIPTION
+    This script automates the detection or installation of libclang on Windows machines.
+    It will:
+      1. Check existing environment variables and well-known locations for libclang.dll
+      2. Optionally install LLVM via winget or Chocolatey if libclang is missing
+      3. Configure the LIBCLANG_PATH environment variable (user scope) once libclang is found
+      4. Optionally append the path to the current session PATH so cargo build/test immediately picks it up
+
+    Run it from the repository root before building Rust components that depend on bindgen (e.g., zstd-sys).
+
+.PARAMETER ForceInstall
+    Always attempt to (re)install LLVM even if libclang is already detected.
+
+.PARAMETER ConfigureCurrentProcess
+    Also updates $env:LIBCLANG_PATH and $env:PATH for the current PowerShell session
+    in addition to setting the persisted user-level environment variable.
+
+.PARAMETER SkipInstall
+    Do not attempt to install LLVM automatically. The script will fail if libclang is not found.
+
+.EXAMPLE
+    pwsh ./scripts/setup-libclang.ps1
+
+.EXAMPLE
+    pwsh ./scripts/setup-libclang.ps1 -ConfigureCurrentProcess
+
+.NOTES
+    - Requires either winget or Chocolatey for automated installation.
+    - When installing via winget, administrative consent may be required for the first run.
+    - After the user-level environment variable is written you should restart your shell (unless ConfigureCurrentProcess was supplied).
+#>
+[CmdletBinding()]
+param(
+    [switch]$ForceInstall,
+    [switch]$ConfigureCurrentProcess,
+    [switch]$SkipInstall
+)
+
+function Write-Info {
+    param([string]$Message)
+    Write-Host "[INFO]  $Message" -ForegroundColor Cyan
+}
+
+function Write-Success {
+    param([string]$Message)
+    Write-Host "[ OK ]  $Message" -ForegroundColor Green
+}
+
+function Write-WarningMessage {
+    param([string]$Message)
+    Write-Host "[WARN]  $Message" -ForegroundColor Yellow
+}
+
+function Write-ErrorMessage {
+    param([string]$Message)
+    Write-Host "[FAIL]  $Message" -ForegroundColor Red
+}
+
+function Test-CommandExists {
+    param([string]$Name)
+    return [bool](Get-Command $Name -ErrorAction SilentlyContinue)
+}
+
+function Get-EnvLibClangPath {
+    $env:LIBCLANG_PATH
+}
+
+function Test-LibClangInPath {
+    param([string]$Directory)
+    if ([string]::IsNullOrWhiteSpace($Directory)) {
+        return $null
+    }
+    $candidate = Join-Path -Path $Directory -ChildPath "libclang.dll"
+    if (Test-Path $candidate) {
+        return (Get-Item $candidate).Directory.FullName
+    }
+    return $null
+}
+
+function Get-KnownLibClangLocations {
+    $paths = @()
+
+    # Explicit environment variable first
+    $envPath = Get-EnvLibClangPath
+    if (-not [string]::IsNullOrWhiteSpace($envPath)) {
+        $paths += $envPath
+    }
+
+    # LLVM default installation
+    $paths += @(
+        "$env:ProgramFiles\LLVM\bin",
+        "$env:ProgramFiles\LLVM\lib",
+        "$env:ProgramFiles\LLVM\lib64",
+        "$env:ProgramFiles(x86)\LLVM\bin",
+        "$env:ProgramFiles(x86)\LLVM\lib"
+    )
+
+    # Visual Studio (MSVC) bundled LLVM/Clang
+    $vsRoot = Join-Path $env:ProgramFiles "Microsoft Visual Studio"
+    if (Test-Path $vsRoot) {
+        $paths += Get-ChildItem -Path $vsRoot -Directory -Recurse -Filter "libclang.dll" -ErrorAction SilentlyContinue |
+            ForEach-Object { $_.Directory.FullName } |
+            Select-Object -Unique
+    }
+
+    # Generic entries that appear in PATH (e.g., if user installed LLVM elsewhere)
+    $paths += [Environment]::GetEnvironmentVariable("PATH", "Machine").Split(';')
+    $paths += [Environment]::GetEnvironmentVariable("PATH", "User").Split(';')
+
+    # Remove duplicates/empty
+    return $paths | Where-Object { -not [string]::IsNullOrWhiteSpace($_) } | Select-Object -Unique
+}
+
+function Find-LibClang {
+    $locations = Get-KnownLibClangLocations
+    foreach ($location in $locations) {
+        $resolved = Test-LibClangInPath -Directory $location
+        if ($resolved) {
+            return $resolved
+        }
+    }
+    return $null
+}
+
+function Install-LLVM {
+    Write-Info "Attempting to install LLVM (includes libclang)..."
+
+    if (Test-CommandExists -Name "winget") {
+        try {
+            winget install LLVM.LLVM --silent --accept-package-agreements --accept-source-agreements | Out-Null
+            Write-Success "LLVM installed via winget"
+            return $true
+        }
+        catch {
+            Write-WarningMessage "winget install failed: $($_.Exception.Message)"
+        }
+    }
+    elseif (Test-CommandExists -Name "choco") {
+        try {
+            choco install llvm -y --no-progress | Out-Null
+            Write-Success "LLVM installed via Chocolatey"
+            return $true
+        }
+        catch {
+            Write-WarningMessage "Chocolatey install failed: $($_.Exception.Message)"
+        }
+    }
+    else {
+        Write-WarningMessage "Neither winget nor Chocolatey is available for automated installation."
+    }
+
+    return $false
+}
+
+function Set-LibClangEnvironment {
+    param(
+        [Parameter(Mandatory = $true)][string]$Directory,
+        [switch]$ConfigureProcess
+    )
+
+    Write-Info "Setting LIBCLANG_PATH user environment variable to '$Directory'"
+    [Environment]::SetEnvironmentVariable("LIBCLANG_PATH", $Directory, "User")
+
+    if ($ConfigureProcess) {
+        $env:LIBCLANG_PATH = $Directory
+        if ($env:PATH -notlike "*$Directory*") {
+            $env:PATH = "$Directory;$env:PATH"
+        }
+        Write-Info "Updated current session PATH for immediate use"
+    }
+
+    Write-Success "LIBCLANG_PATH configured. Restart PowerShell or open a new terminal to pick up user-level changes."
+}
+
+try {
+    if ($ForceInstall -and $SkipInstall) {
+        throw "Cannot use -ForceInstall together with -SkipInstall."
+    }
+
+    $libclangDir = Find-LibClang
+
+    if ($ForceInstall -or (-not $libclangDir)) {
+        if ($SkipInstall) {
+            throw "libclang was not found and installation is disabled (SkipInstall)."
+        }
+        $installed = Install-LLVM
+        if (-not $installed) {
+            throw "Automatic LLVM installation failed. Please install LLVM manually and rerun this script."
+        }
+        $libclangDir = Find-LibClang
+    }
+
+    if (-not $libclangDir) {
+        throw "libclang.dll could not be located even after installation. Please install LLVM manually and rerun."
+    }
+
+    Write-Success "Found libclang at '$libclangDir'"
+    Set-LibClangEnvironment -Directory $libclangDir -ConfigureProcess:$ConfigureCurrentProcess
+
+    Write-Info "You can now run 'cargo build' / 'cargo test' successfully."
+}
+catch {
+    Write-ErrorMessage $_
+    exit 1
+}

package/src/benchmarks/memory-benchmarks.ts

@@ -0,0 +1,316 @@
+#!/usr/bin/env -S deno run -A
+
+import { GunDB } from "../core/database.ts";
+
+interface MemoryMetrics {
+  operation: string;
+  initialMemory: number;
+  finalMemory: number;
+  memoryIncrease: number;
+  recordCount: number;
+  memoryPerRecord: number;
+}
+
+class MemoryBenchmark {
+  private results: MemoryMetrics[] = [];
+
+  private getMemoryUsage(): number {
+    return (performance as any).memory?.usedJSHeapSize || 0;
+  }
+
+  async measureMemoryUsage(
+    operation: string,
+    recordCount: number,
+    operationFn: () => Promise<void>,
+  ): Promise<MemoryMetrics> {
+    console.log(`Measuring memory usage for: ${operation}`);
+
+    // Force garbage collection if available
+    if ((globalThis as any).gc) {
+      (globalThis as any).gc();
+    }
+
+    const initialMemory = this.getMemoryUsage();
+
+    await operationFn();
+
+    // Force garbage collection if available
+    if ((globalThis as any).gc) {
+      (globalThis as any).gc();
+    }
+
+    const finalMemory = this.getMemoryUsage();
+    const memoryIncrease = finalMemory - initialMemory;
+    const memoryPerRecord = memoryIncrease / recordCount;
+
+    const metrics: MemoryMetrics = {
+      operation,
+      initialMemory,
+      finalMemory,
+      memoryIncrease,
+      recordCount,
+      memoryPerRecord,
+    };
+
+    this.results.push(metrics);
+
+    console.log(`  Initial Memory: ${(initialMemory / 1024 / 1024).toFixed(2)}MB`);
+    console.log(`  Final Memory: ${(finalMemory / 1024 / 1024).toFixed(2)}MB`);
+    console.log(`  Memory Increase: ${(memoryIncrease / 1024 / 1024).toFixed(2)}MB`);
+    console.log(`  Memory per Record: ${memoryPerRecord.toFixed(2)} bytes`);
+    console.log();
+
+    return metrics;
+  }
+
+  printSummary() {
+    console.log("\n" + "=".repeat(80));
+    console.log("MEMORY USAGE SUMMARY");
+    console.log("=".repeat(80));
+
+    this.results.forEach((result) => {
+      console.log(`${result.operation}:`);
+      console.log(`  Records: ${result.recordCount.toLocaleString()}`);
+      console.log(`  Memory Increase: ${(result.memoryIncrease / 1024 / 1024).toFixed(2)}MB`);
+      console.log(`  Memory per Record: ${result.memoryPerRecord.toFixed(2)} bytes`);
+      console.log();
+    });
+  }
+}
+
+async function runMemoryBenchmarks() {
+  const benchmark = new MemoryBenchmark();
+  const db = new GunDB();
+
+  try {
+    const kvPath = await Deno.makeTempFile({
+      prefix: "kv_",
+      suffix: ".sqlite",
+    });
+    await db.ready(kvPath);
+
+    console.log("Starting Memory Benchmarks...\n");
+
+    // Benchmark 1: Small Records
+    await benchmark.measureMemoryUsage("Small Records (100 bytes)", 1000, async () => {
+      for (let i = 0; i < 1000; i++) {
+        await db.put(`small:${i}`, {
+          id: i,
+          data: "x".repeat(100),
+          timestamp: Date.now(),
+        });
+      }
+    });
+
+    // Benchmark 2: Medium Records
+    await benchmark.measureMemoryUsage("Medium Records (1KB)", 1000, async () => {
+      for (let i = 0; i < 1000; i++) {
+        await db.put(`medium:${i}`, {
+          id: i,
+          data: "x".repeat(1024),
+          timestamp: Date.now(),
+          metadata: { size: "medium", type: "test" },
+        });
+      }
+    });
+
+    // Benchmark 3: Large Records
+    await benchmark.measureMemoryUsage("Large Records (10KB)", 100, async () => {
+      for (let i = 0; i < 100; i++) {
+        await db.put(`large:${i}`, {
+          id: i,
+          data: "x".repeat(10 * 1024),
+          timestamp: Date.now(),
+          metadata: { size: "large", type: "test" },
+          additional: "y".repeat(1024),
+        });
+      }
+    });
+
+    // Benchmark 4: Vector Data
+    await benchmark.measureMemoryUsage("Vector Data (100 dimensions)", 500, async () => {
+      for (let i = 0; i < 500; i++) {
+        const vector = Array.from({ length: 100 }, () => Math.random());
+        await db.put(`vector:${i}`, {
+          id: i,
+          text: `Document ${i} with vector data`,
+          vector: vector,
+          timestamp: Date.now(),
+        });
+      }
+    });
+
+    // Benchmark 5: Nested Objects
+    await benchmark.measureMemoryUsage("Nested Objects", 500, async () => {
+      for (let i = 0; i < 500; i++) {
+        await db.put(`nested:${i}`, {
+          id: i,
+          user: {
+            name: `User ${i}`,
+            email: `user${i}@example.com`,
+            profile: {
+              age: 20 + (i % 50),
+              location: `City ${i}`,
+              preferences: {
+                theme: i % 2 === 0 ? "dark" : "light",
+                notifications: true,
+                privacy: "public",
+              },
+            },
+          },
+          metadata: {
+            created: Date.now(),
+            updated: Date.now(),
+            version: 1,
+          },
+        });
+      }
+    });
+
+    // Benchmark 6: Subscriptions Memory Usage
+    await benchmark.measureMemoryUsage("Subscriptions", 1000, async () => {
+      const subscriptions: Array<() => void> = [];
+      for (let i = 0; i < 1000; i++) {
+        const unsubscribe = db.on(`sub:${i}`, () => {});
+        subscriptions.push(unsubscribe);
+      }
+
+      // Store subscriptions for cleanup
+      (globalThis as any).subscriptions = subscriptions;
+    });
+
+    // Clean up subscriptions
+    if ((globalThis as any).subscriptions) {
+      ((globalThis as any).subscriptions as Array<() => void>).forEach((unsubscribe) =>
+        unsubscribe(),
+      );
+      delete (globalThis as any).subscriptions;
+    }
+
+    // Benchmark 7: Type System Memory Usage
+    await benchmark.measureMemoryUsage("Type System", 1000, async () => {
+      for (let i = 0; i < 1000; i++) {
+        await db.put(`type:${i}`, { name: `Item ${i}` });
+        await db.setType(`type:${i}`, "TestItem");
+      }
+    });
+
+    // Benchmark 8: CRDT Operations Memory Usage
+    await benchmark.measureMemoryUsage("CRDT Operations", 1000, async () => {
+      for (let i = 0; i < 1000; i++) {
+        await db.put(`crdt:${i}`, {
+          value: i,
+          timestamp: Date.now(),
+          vectorClock: { peer1: i, peer2: i * 2 },
+        });
+      }
+    });
+
+    benchmark.printSummary();
+  } finally {
+    await db.close();
+  }
+}
+
+async function runMemoryLeakTests() {
+  console.log("\n" + "=".repeat(80));
+  console.log("MEMORY LEAK TESTS");
+  console.log("=".repeat(80));
+
+  const db = new GunDB();
+  try {
+    const kvPath = await Deno.makeTempFile({
+      prefix: "kv_",
+      suffix: ".sqlite",
+    });
+    await db.ready(kvPath);
+
+    // Test 1: Subscription Memory Leaks
+    console.log("Testing subscription memory leaks...");
+
+    const initialMemory = (performance as any).memory?.usedJSHeapSize || 0;
+
+    // Create and destroy many subscriptions
+    for (let cycle = 0; cycle < 10; cycle++) {
+      const subscriptions: Array<() => void> = [];
+
+      for (let i = 0; i < 100; i++) {
+        subscriptions.push(db.on(`leak:${cycle}:${i}`, () => {}));
+      }
+
+      // Destroy all subscriptions
+      subscriptions.forEach((unsubscribe) => unsubscribe());
+
+      // Force garbage collection if available
+      if ((globalThis as any).gc) {
+        (globalThis as any).gc();
+      }
+    }
+
+    const finalMemory = (performance as any).memory?.usedJSHeapSize || 0;
+    const memoryIncrease = finalMemory - initialMemory;
+
+    console.log(
+      `Memory increase after subscription cycles: ${(memoryIncrease / 1024).toFixed(2)}KB`,
+    );
+
+    if (memoryIncrease > 1024 * 1024) {
+      // More than 1MB
+      console.log("⚠️  Potential memory leak detected in subscriptions");
+    } else {
+      console.log("✓ No significant memory leak in subscriptions");
+    }
+
+    // Test 2: CRUD Operations Memory Leaks
+    console.log("\nTesting CRUD operations memory leaks...");
+
+    const crudInitialMemory = (performance as any).memory?.usedJSHeapSize || 0;
+
+    // Perform many CRUD operations
+    for (let cycle = 0; cycle < 100; cycle++) {
+      for (let i = 0; i < 100; i++) {
+        await db.put(`leak:${cycle}:${i}`, { data: `Cycle ${cycle} Item ${i}` });
+        await db.get(`leak:${cycle}:${i}`);
+        await db.delete(`leak:${cycle}:${i}`);
+      }
+
+      // Force garbage collection if available
+      if ((globalThis as any).gc) {
+        (globalThis as any).gc();
+      }
+    }
+
+    const crudFinalMemory = (performance as any).memory?.usedJSHeapSize || 0;
+    const crudMemoryIncrease = crudFinalMemory - crudInitialMemory;
+
+    console.log(`Memory increase after CRUD cycles: ${(crudMemoryIncrease / 1024).toFixed(2)}KB`);
+
+    if (crudMemoryIncrease > 1024 * 1024) {
+      // More than 1MB
+      console.log("⚠️  Potential memory leak detected in CRUD operations");
+    } else {
+      console.log("✓ No significant memory leak in CRUD operations");
+    }
+  } finally {
+    await db.close();
+  }
+}
+
+async function main() {
+  console.log("PluresDB Memory Benchmarks");
+  console.log("===========================\n");
+
+  try {
+    await runMemoryBenchmarks();
+    await runMemoryLeakTests();
+
+    console.log("\nMemory benchmarks completed successfully!");
+  } catch (error) {
+    console.error("Memory benchmark failed:", error);
+    Deno.exit(1);
+  }
+}
+
+if (import.meta.main) {
+  await main();
+}