fss-link 1.2.0 → 1.2.1

package/dist/src/config/database-monitor.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Database Performance Monitor
+ *
+ * Tracks database operation timing, queue depth, and overall system health
+ * to verify the effectiveness of the async locking system in eliminating
+ * race conditions and maintaining performance.
+ *
+ * @author Lewis - Technical breakthrough coordinator
+ */
+export declare class DatabasePerformanceMonitor {
+    private static instance;
+    private operations;
+    private isMonitoring;
+    private monitoringInterval?;
+    private stats;
+    /**
+     * Get the singleton instance
+     */
+    static getInstance(): DatabasePerformanceMonitor;
+    /**
+     * Start monitoring database operations
+     */
+    startMonitoring(intervalMs?: number): void;
+    /**
+     * Stop monitoring database operations
+     */
+    stopMonitoring(): void;
+    /**
+     * Record a database operation for performance tracking
+     */
+    recordOperation(operationName: string, duration: number, success: boolean, queueWaitTime?: number): void;
+    /**
+     * Get current performance statistics
+     */
+    getStats(): SystemStats;
+    /**
+     * Get recent operation history
+     */
+    getRecentOperations(count?: number): OperationMetrics[];
+    /**
+     * Generate a comprehensive performance report
+     */
+    generateReport(): PerformanceReport;
+    /**
+     * Check if the system is performing optimally
+     */
+    isSystemHealthy(): boolean;
+    /**
+     * Detect potential race conditions
+     */
+    detectRaceConditions(): RaceConditionAnalysis;
+    /**
+     * Export performance data for analysis
+     */
+    exportData(): DatabasePerformanceData;
+    /**
+     * Clear all collected data
+     */
+    reset(): void;
+    private collectQueueStats;
+    private updateStats;
+    private logOperation;
+    private calculateAverageQueueDepth;
+    private calculateQueueUtilization;
+    private determineHealthStatus;
+    private printSummaryReport;
+}
+interface OperationMetrics {
+    name: string;
+    duration: number;
+    success: boolean;
+    queueWaitTime: number;
+    timestamp: number;
+}
+interface SystemStats {
+    totalOperations: number;
+    totalTime: number;
+    averageTime: number;
+    maxTime: number;
+    minTime: number;
+    queueDepthHistory: number[];
+    errorCount: number;
+    concurrentOperationsDetected: number;
+}
+interface PerformanceReport {
+    summary: {
+        totalOperations: number;
+        averageOperationTime: number;
+        maxOperationTime: number;
+        minOperationTime: number;
+        errorRate: number;
+        concurrentOperationsDetected: number;
+    };
+    queueAnalysis: {
+        averageQueueDepth: number;
+        maxQueueDepth: number;
+        queueUtilization: number;
+    };
+    recentOperations: OperationMetrics[];
+    healthStatus: 'excellent' | 'good' | 'warning' | 'critical';
+}
+interface RaceConditionAnalysis {
+    suspiciousPatterns: string[];
+    concurrentOperationsCount: number;
+    recommendations: string[];
+}
+interface DatabasePerformanceData {
+    timestamp: number;
+    stats: SystemStats;
+    operations: OperationMetrics[];
+    report: PerformanceReport;
+    raceConditionAnalysis: RaceConditionAnalysis;
+}
+/**
+ * Global monitor instance for easy access
+ */
+export declare const databaseMonitor: DatabasePerformanceMonitor;
+/**
+ * Utility function to wrap database operations with monitoring
+ */
+export declare function monitorDatabaseOperation<T>(operationName: string, operation: () => Promise<T>): Promise<T>;
+/**
+ * Start monitoring with default settings
+ */
+export declare function startDatabaseMonitoring(): void;
+/**
+ * Stop monitoring and show summary
+ */
+export declare function stopDatabaseMonitoring(): void;
+export {};

package/dist/src/config/database-monitor.js

@@ -0,0 +1,306 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DatabaseOperationQueue } from './database-queue.js';
+/**
+ * Database Performance Monitor
+ *
+ * Tracks database operation timing, queue depth, and overall system health
+ * to verify the effectiveness of the async locking system in eliminating
+ * race conditions and maintaining performance.
+ *
+ * @author Lewis - Technical breakthrough coordinator
+ */
+export class DatabasePerformanceMonitor {
+    static instance;
+    operations = [];
+    isMonitoring = false;
+    monitoringInterval;
+    stats = {
+        totalOperations: 0,
+        totalTime: 0,
+        averageTime: 0,
+        maxTime: 0,
+        minTime: Infinity,
+        queueDepthHistory: [],
+        errorCount: 0,
+        concurrentOperationsDetected: 0
+    };
+    /**
+     * Get the singleton instance
+     */
+    static getInstance() {
+        if (!DatabasePerformanceMonitor.instance) {
+            DatabasePerformanceMonitor.instance = new DatabasePerformanceMonitor();
+        }
+        return DatabasePerformanceMonitor.instance;
+    }
+    /**
+     * Start monitoring database operations
+     */
+    startMonitoring(intervalMs = 1000) {
+        if (this.isMonitoring) {
+            console.log('📊 [DB-MONITOR] Monitoring already active');
+            return;
+        }
+        this.isMonitoring = true;
+        console.log('📊 [DB-MONITOR] Performance monitoring started');
+        // Monitor queue statistics every second
+        this.monitoringInterval = setInterval(() => {
+            this.collectQueueStats();
+        }, intervalMs);
+    }
+    /**
+     * Stop monitoring database operations
+     */
+    stopMonitoring() {
+        if (!this.isMonitoring) {
+            return;
+        }
+        this.isMonitoring = false;
+        if (this.monitoringInterval) {
+            clearInterval(this.monitoringInterval);
+            this.monitoringInterval = undefined;
+        }
+        console.log('📊 [DB-MONITOR] Performance monitoring stopped');
+        this.printSummaryReport();
+    }
+    /**
+     * Record a database operation for performance tracking
+     */
+    recordOperation(operationName, duration, success, queueWaitTime) {
+        const operation = {
+            name: operationName,
+            duration,
+            success,
+            queueWaitTime: queueWaitTime || 0,
+            timestamp: Date.now()
+        };
+        this.operations.push(operation);
+        this.updateStats(operation);
+        // Keep only last 1000 operations to prevent memory bloat
+        if (this.operations.length > 1000) {
+            this.operations = this.operations.slice(-1000);
+        }
+        this.logOperation(operation);
+    }
+    /**
+     * Get current performance statistics
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Get recent operation history
+     */
+    getRecentOperations(count = 50) {
+        return this.operations.slice(-count);
+    }
+    /**
+     * Generate a comprehensive performance report
+     */
+    generateReport() {
+        const recentOps = this.getRecentOperations(100);
+        const errorRate = (this.stats.errorCount / this.stats.totalOperations) * 100;
+        return {
+            summary: {
+                totalOperations: this.stats.totalOperations,
+                averageOperationTime: Math.round(this.stats.averageTime * 100) / 100,
+                maxOperationTime: this.stats.maxTime,
+                minOperationTime: this.stats.minTime === Infinity ? 0 : this.stats.minTime,
+                errorRate: Math.round(errorRate * 100) / 100,
+                concurrentOperationsDetected: this.stats.concurrentOperationsDetected
+            },
+            queueAnalysis: {
+                averageQueueDepth: this.calculateAverageQueueDepth(),
+                maxQueueDepth: Math.max(...this.stats.queueDepthHistory),
+                queueUtilization: this.calculateQueueUtilization()
+            },
+            recentOperations: recentOps,
+            healthStatus: this.determineHealthStatus()
+        };
+    }
+    /**
+     * Check if the system is performing optimally
+     */
+    isSystemHealthy() {
+        const errorRate = (this.stats.errorCount / this.stats.totalOperations) * 100;
+        const avgTime = this.stats.averageTime;
+        return (errorRate < 1 && // Less than 1% error rate
+            avgTime < 100 && // Average operation under 100ms
+            this.stats.concurrentOperationsDetected === 0 // No race conditions detected
+        );
+    }
+    /**
+     * Detect potential race conditions
+     */
+    detectRaceConditions() {
+        const analysis = {
+            suspiciousPatterns: [],
+            concurrentOperationsCount: this.stats.concurrentOperationsDetected,
+            recommendations: []
+        };
+        // Check for concurrent operations (should be 0 with proper locking)
+        if (this.stats.concurrentOperationsDetected > 0) {
+            analysis.suspiciousPatterns.push('Concurrent database operations detected');
+            analysis.recommendations.push('Review async locking implementation');
+        }
+        // Check for unusually long operations
+        const longOperations = this.operations.filter(op => op.duration > 1000);
+        if (longOperations.length > 0) {
+            analysis.suspiciousPatterns.push(`${longOperations.length} operations took >1 second`);
+            analysis.recommendations.push('Investigate slow database queries');
+        }
+        // Check error clustering
+        const recentErrors = this.operations
+            .filter(op => !op.success)
+            .slice(-10);
+        if (recentErrors.length > 3) {
+            analysis.suspiciousPatterns.push('High error rate in recent operations');
+            analysis.recommendations.push('Check database connection stability');
+        }
+        return analysis;
+    }
+    /**
+     * Export performance data for analysis
+     */
+    exportData() {
+        return {
+            timestamp: Date.now(),
+            stats: this.getStats(),
+            operations: [...this.operations],
+            report: this.generateReport(),
+            raceConditionAnalysis: this.detectRaceConditions()
+        };
+    }
+    /**
+     * Clear all collected data
+     */
+    reset() {
+        this.operations = [];
+        this.stats = {
+            totalOperations: 0,
+            totalTime: 0,
+            averageTime: 0,
+            maxTime: 0,
+            minTime: Infinity,
+            queueDepthHistory: [],
+            errorCount: 0,
+            concurrentOperationsDetected: 0
+        };
+        console.log('📊 [DB-MONITOR] All performance data cleared');
+    }
+    // Private methods
+    collectQueueStats() {
+        const queue = DatabaseOperationQueue.getInstance();
+        const queueStats = queue.getQueueStats();
+        this.stats.queueDepthHistory.push(queueStats.queueLength);
+        // Keep only last 100 queue depth measurements
+        if (this.stats.queueDepthHistory.length > 100) {
+            this.stats.queueDepthHistory = this.stats.queueDepthHistory.slice(-100);
+        }
+        // Detect concurrent operations (should never happen with proper locking)
+        if (queueStats.queueLength > 0 && queueStats.isLocked) {
+            // This is normal - operations waiting in queue
+        }
+        else if (queueStats.queueLength > 1) {
+            // This might indicate a problem
+            this.stats.concurrentOperationsDetected++;
+        }
+    }
+    updateStats(operation) {
+        this.stats.totalOperations++;
+        this.stats.totalTime += operation.duration;
+        this.stats.averageTime = this.stats.totalTime / this.stats.totalOperations;
+        this.stats.maxTime = Math.max(this.stats.maxTime, operation.duration);
+        this.stats.minTime = Math.min(this.stats.minTime, operation.duration);
+        if (!operation.success) {
+            this.stats.errorCount++;
+        }
+    }
+    logOperation(operation) {
+        if (process.env['DEBUG_DB_MONITOR'] === 'true') {
+            const status = operation.success ? '✅' : '❌';
+            const queueInfo = operation.queueWaitTime > 0 ? ` (waited ${operation.queueWaitTime}ms)` : '';
+            console.log(`📊 [DB-MONITOR] ${status} ${operation.name}: ${operation.duration}ms${queueInfo}`);
+        }
+    }
+    calculateAverageQueueDepth() {
+        if (this.stats.queueDepthHistory.length === 0)
+            return 0;
+        const sum = this.stats.queueDepthHistory.reduce((a, b) => a + b, 0);
+        return Math.round((sum / this.stats.queueDepthHistory.length) * 100) / 100;
+    }
+    calculateQueueUtilization() {
+        const nonZeroQueue = this.stats.queueDepthHistory.filter(depth => depth > 0);
+        return Math.round((nonZeroQueue.length / this.stats.queueDepthHistory.length) * 100);
+    }
+    determineHealthStatus() {
+        const errorRate = (this.stats.errorCount / this.stats.totalOperations) * 100;
+        const avgTime = this.stats.averageTime;
+        const hasRaceConditions = this.stats.concurrentOperationsDetected > 0;
+        if (hasRaceConditions || errorRate > 5) {
+            return 'critical';
+        }
+        else if (errorRate > 2 || avgTime > 200) {
+            return 'warning';
+        }
+        else if (errorRate < 1 && avgTime < 50) {
+            return 'excellent';
+        }
+        else {
+            return 'good';
+        }
+    }
+    printSummaryReport() {
+        const report = this.generateReport();
+        console.log('\n📊 DATABASE PERFORMANCE MONITORING SUMMARY');
+        console.log('==========================================');
+        console.log(`Total Operations: ${report.summary.totalOperations}`);
+        console.log(`Average Time: ${report.summary.averageOperationTime}ms`);
+        console.log(`Max Time: ${report.summary.maxOperationTime}ms`);
+        console.log(`Error Rate: ${report.summary.errorRate}%`);
+        console.log(`Health Status: ${report.healthStatus.toUpperCase()}`);
+        console.log(`Race Conditions: ${report.summary.concurrentOperationsDetected}`);
+        console.log(`Average Queue Depth: ${report.queueAnalysis.averageQueueDepth}`);
+        console.log(`Max Queue Depth: ${report.queueAnalysis.maxQueueDepth}`);
+        console.log('==========================================\n');
+    }
+}
+/**
+ * Global monitor instance for easy access
+ */
+export const databaseMonitor = DatabasePerformanceMonitor.getInstance();
+/**
+ * Utility function to wrap database operations with monitoring
+ */
+export async function monitorDatabaseOperation(operationName, operation) {
+    const monitor = DatabasePerformanceMonitor.getInstance();
+    const startTime = Date.now();
+    try {
+        const result = await operation();
+        const duration = Date.now() - startTime;
+        monitor.recordOperation(operationName, duration, true);
+        return result;
+    }
+    catch (error) {
+        const duration = Date.now() - startTime;
+        monitor.recordOperation(operationName, duration, false);
+        throw error;
+    }
+}
+/**
+ * Start monitoring with default settings
+ */
+export function startDatabaseMonitoring() {
+    databaseMonitor.startMonitoring();
+}
+/**
+ * Stop monitoring and show summary
+ */
+export function stopDatabaseMonitoring() {
+    databaseMonitor.stopMonitoring();
+}
+//# sourceMappingURL=database-monitor.js.map

package/dist/src/config/database-monitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-monitor.js","sourceRoot":"","sources":["../../../src/config/database-monitor.ts"],"names":[],"mappings":"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"}

package/dist/src/config/database-queue.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * DatabaseOperationQueue - Singleton operation serializer
+ *
+ * Ensures all database operations execute one at a time to prevent
+ * "Statement closed" errors and race conditions. Uses George's brilliant
+ * AsyncMutex for thread-safe operation queuing.
+ *
+ * @author Lewis - Technical breakthrough coordinator
+ */
+export declare class DatabaseOperationQueue {
+    private static instance;
+    private mutex;
+    private operationCounter;
+    private successfulOperations;
+    private failedOperations;
+    private debugEnabled;
+    private performanceTracking;
+    /**
+     * Get the singleton instance (thread-safe)
+     */
+    static getInstance(): DatabaseOperationQueue;
+    /**
+     * Execute a database operation with full serialization protection
+     *
+     * @param operation The async database operation to execute
+     * @param operationName Optional name for debugging/logging
+     * @returns Promise with the operation result
+     */
+    executeOperation<T>(operation: () => Promise<T>, operationName?: string): Promise<T>;
+    /**
+     * Execute multiple operations as a batch (still serialized)
+     * Useful for related operations that should be grouped
+     *
+     * @param operations Array of operations to execute
+     * @param batchName Optional name for the batch
+     * @returns Promise with array of results
+     */
+    executeBatch<T>(operations: Array<() => Promise<T>>, batchName?: string): Promise<T[]>;
+    /**
+     * Get current queue statistics for monitoring
+     */
+    getQueueStats(): {
+        queueLength: number;
+        isLocked: boolean;
+        operationCounter: number;
+    };
+    /**
+     * Wait for all queued operations to complete
+     * Useful for shutdown or testing scenarios
+     */
+    waitForIdle(): Promise<void>;
+    /**
+     * Emergency shutdown - force clear all operations
+     * WARNING: Only use for testing or emergency cleanup
+     */
+    forceShutdown(): void;
+    /**
+     * Debug logging (enabled with DEBUG_DB_QUEUE=true)
+     */
+    private debugLog;
+    /**
+     * Error logging (always enabled for critical errors)
+     */
+    private errorLog;
+    /**
+     * Enable debug logging programmatically
+     */
+    enableDebug(): void;
+    /**
+     * Enable performance tracking programmatically
+     */
+    enablePerformanceTracking(): void;
+    /**
+     * Get comprehensive queue statistics for monitoring and debugging
+     * Required by database regression tests
+     */
+    getStatistics(): {
+        queueLength: number;
+        isLocked: boolean;
+        operationCounter: number;
+        totalOperations: number;
+        totalSuccessful: number;
+        totalErrors: number;
+        debugEnabled: boolean;
+        performanceTracking: boolean;
+    };
+}
+/**
+ * Utility function to execute an operation with database queue protection
+ * Convenience wrapper for common usage patterns
+ *
+ * @param operation The async operation to execute
+ * @param operationName Optional name for debugging
+ * @returns Promise with the operation result
+ */
+export declare function withDatabaseQueue<T>(operation: () => Promise<T>, operationName?: string): Promise<T>;
+/**
+ * Get the global database queue instance
+ * Convenience function for easy access
+ */
+export declare function getDatabaseQueue(): DatabaseOperationQueue;