keynesol-shared 1.0.0

package/src/utils/cacheManager.ts

@@ -0,0 +1,286 @@
+/**
+ * Cache Manager
+ * Multi-level caching system for blockchain data
+ * Requirements: 6.2, 6.3
+ */
+
+export type CacheStrategy = 'lru' | 'lfu' | 'fifo';
+
+export interface CacheConfig {
+  ttl: number; // milliseconds
+  maxSize?: number; // maximum cache entries
+  strategy: CacheStrategy;
+}
+
+export interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+  hits: number;
+  ttl: number;
+}
+
+export interface CacheStats {
+  hits: number;
+  misses: number;
+  hitRate: number;
+  size: number;
+  oldestEntry: number;
+  newestEntry: number;
+}
+
+class CacheManager {
+  private caches: Map<string, Map<string, CacheEntry<any>>> = new Map();
+  private stats: Map<string, { hits: number; misses: number }> = new Map();
+  private configs: Map<string, CacheConfig> = new Map();
+
+  /**
+   * Get cached data
+   */
+  get<T>(namespace: string, key: string): T | null {
+    const cache = this.caches.get(namespace);
+    if (!cache) {
+      this.recordMiss(namespace);
+      return null;
+    }
+
+    const entry = cache.get(key);
+    if (!entry) {
+      this.recordMiss(namespace);
+      return null;
+    }
+
+    // Check if entry is expired
+    const now = Date.now();
+    if (now - entry.timestamp > entry.ttl) {
+      cache.delete(key);
+      this.recordMiss(namespace);
+      return null;
+    }
+
+    // Update hit count
+    entry.hits++;
+    this.recordHit(namespace);
+
+    return entry.data as T;
+  }
+
+  /**
+   * Set cached data
+   */
+  set<T>(namespace: string, key: string, data: T, ttl?: number): void {
+    const config = this.configs.get(namespace);
+    if (!config) {
+      console.warn(`No config found for namespace: ${namespace}`);
+      return;
+    }
+
+    let cache = this.caches.get(namespace);
+    if (!cache) {
+      cache = new Map();
+      this.caches.set(namespace, cache);
+      this.stats.set(namespace, { hits: 0, misses: 0 });
+    }
+
+    const entryTtl = ttl || config.ttl;
+    const entry: CacheEntry<T> = {
+      data,
+      timestamp: Date.now(),
+      hits: 0,
+      ttl: entryTtl,
+    };
+
+    // Check max size and evict if needed
+    if (config.maxSize && cache.size >= config.maxSize) {
+      this.evict(namespace, cache, config.strategy);
+    }
+
+    cache.set(key, entry);
+  }
+
+  /**
+   * Invalidate cache entry or entire namespace
+   */
+  invalidate(namespace: string, key?: string): void {
+    const cache = this.caches.get(namespace);
+    if (!cache) return;
+
+    if (key) {
+      cache.delete(key);
+    } else {
+      cache.clear();
+    }
+  }
+
+  /**
+   * Clear all caches or specific namespace
+   */
+  clear(namespace?: string): void {
+    if (namespace) {
+      this.caches.delete(namespace);
+      this.stats.delete(namespace);
+    } else {
+      this.caches.clear();
+      this.stats.clear();
+    }
+  }
+
+  /**
+   * Configure cache for namespace
+   */
+  configure(namespace: string, config: CacheConfig): void {
+    this.configs.set(namespace, config);
+    if (!this.stats.has(namespace)) {
+      this.stats.set(namespace, { hits: 0, misses: 0 });
+    }
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(namespace: string): CacheStats | null {
+    const cache = this.caches.get(namespace);
+    const stats = this.stats.get(namespace);
+    if (!cache || !stats) return null;
+
+    const entries = Array.from(cache.values());
+    const timestamps = entries.map(e => e.timestamp);
+    const totalRequests = stats.hits + stats.misses;
+    const hitRate = totalRequests > 0 ? stats.hits / totalRequests : 0;
+
+    return {
+      hits: stats.hits,
+      misses: stats.misses,
+      hitRate,
+      size: cache.size,
+      oldestEntry: timestamps.length > 0 ? Math.min(...timestamps) : 0,
+      newestEntry: timestamps.length > 0 ? Math.max(...timestamps) : 0,
+    };
+  }
+
+  /**
+   * Evict entry based on strategy
+   */
+  private evict(
+    namespace: string,
+    cache: Map<string, CacheEntry<any>>,
+    strategy: CacheStrategy
+  ): void {
+    let entryToEvict: string | null = null;
+
+    switch (strategy) {
+      case 'lru': {
+        // Evict least recently used (oldest timestamp)
+        let oldestTime = Infinity;
+        const entries = Array.from(cache.entries());
+        for (const [key, entry] of entries) {
+          if (entry.timestamp < oldestTime) {
+            oldestTime = entry.timestamp;
+            entryToEvict = key;
+          }
+        }
+        break;
+      }
+
+      case 'lfu': {
+        // Evict least frequently used (lowest hits)
+        let lowestHits = Infinity;
+        const entries = Array.from(cache.entries());
+        for (const [key, entry] of entries) {
+          if (entry.hits < lowestHits) {
+            lowestHits = entry.hits;
+            entryToEvict = key;
+          }
+        }
+        break;
+      }
+
+      case 'fifo': {
+        // Evict first in (oldest timestamp, same as LRU for simplicity)
+        let oldestTime = Infinity;
+        const entries = Array.from(cache.entries());
+        for (const [key, entry] of entries) {
+          if (entry.timestamp < oldestTime) {
+            oldestTime = entry.timestamp;
+            entryToEvict = key;
+          }
+        }
+        break;
+      }
+    }
+
+    if (entryToEvict) {
+      cache.delete(entryToEvict);
+    }
+  }
+
+  /**
+   * Record cache hit
+   */
+  private recordHit(namespace: string): void {
+    const stats = this.stats.get(namespace);
+    if (stats) {
+      stats.hits++;
+    }
+  }
+
+  /**
+   * Record cache miss
+   */
+  private recordMiss(namespace: string): void {
+    const stats = this.stats.get(namespace);
+    if (stats) {
+      stats.misses++;
+    }
+  }
+
+  /**
+   * Clean expired entries (should be called periodically)
+   */
+  cleanExpired(): void {
+    const now = Date.now();
+    const namespaces = Array.from(this.caches.entries());
+    for (const [namespace, cache] of namespaces) {
+      const entries = Array.from(cache.entries());
+      for (const [key, entry] of entries) {
+        if (now - entry.timestamp > entry.ttl) {
+          cache.delete(key);
+        }
+      }
+    }
+  }
+}
+
+// Export singleton instance
+export const cacheManager = new CacheManager();
+
+// Configure default caches
+cacheManager.configure('vaults', {
+  ttl: 30000, // 30 seconds
+  maxSize: 100,
+  strategy: 'lru',
+});
+
+cacheManager.configure('userStakes', {
+  ttl: 10000, // 10 seconds
+  maxSize: 1000,
+  strategy: 'lru',
+});
+
+cacheManager.configure('platformMetrics', {
+  ttl: 60000, // 1 minute
+  maxSize: 50,
+  strategy: 'lru',
+});
+
+cacheManager.configure('transactions', {
+  ttl: 60000, // 1 minute
+  maxSize: 500,
+  strategy: 'lru',
+});
+
+// Clean expired entries every 5 minutes
+if (typeof window !== 'undefined') {
+  setInterval(() => {
+    cacheManager.cleanExpired();
+  }, 5 * 60 * 1000);
+}

package/src/utils/errorHandler.ts

@@ -0,0 +1,336 @@
+/**
+ * Error Handler Utility
+ * Comprehensive error handling system with classification, retry logic, and user-friendly messages
+ * Requirements: 4.1, 4.2, 4.3, 4.4, 4.5
+ */
+
+export enum ErrorCategory {
+  NETWORK = 'network',
+  BLOCKCHAIN = 'blockchain',
+  VALIDATION = 'validation',
+  AUTHORIZATION = 'authorization',
+  DATA = 'data',
+  UNKNOWN = 'unknown',
+}
+
+export interface ErrorHandlerConfig {
+  retryAttempts?: number;
+  retryDelay?: number; // milliseconds
+  exponentialBackoff?: boolean;
+  onRetry?: (attempt: number, error: Error) => void;
+}
+
+export interface ErrorLog {
+  timestamp: number;
+  level: 'error' | 'warning' | 'info';
+  context: string;
+  message: string;
+  stack?: string;
+  metadata?: Record<string, any>;
+  userId?: string;
+  category: ErrorCategory;
+}
+
+class ErrorHandler {
+  private logs: ErrorLog[] = [];
+  private maxLogs: number = 1000;
+
+  /**
+   * Classify error into category
+   */
+  classifyError(error: Error): ErrorCategory {
+    const message = error.message.toLowerCase();
+    const stack = error.stack?.toLowerCase() || '';
+
+    // Network errors
+    if (
+      message.includes('network') ||
+      message.includes('fetch') ||
+      message.includes('timeout') ||
+      message.includes('connection') ||
+      message.includes('rpc') ||
+      message.includes('failed to fetch')
+    ) {
+      return ErrorCategory.NETWORK;
+    }
+
+    // Blockchain errors
+    if (
+      message.includes('transaction') ||
+      message.includes('insufficient') ||
+      message.includes('program') ||
+      message.includes('account') ||
+      message.includes('anchor') ||
+      message.includes('solana')
+    ) {
+      return ErrorCategory.BLOCKCHAIN;
+    }
+
+    // Validation errors
+    if (
+      message.includes('invalid') ||
+      message.includes('required') ||
+      message.includes('must be') ||
+      message.includes('out of range') ||
+      message.includes('validation')
+    ) {
+      return ErrorCategory.VALIDATION;
+    }
+
+    // Authorization errors
+    if (
+      message.includes('unauthorized') ||
+      message.includes('permission') ||
+      message.includes('access denied') ||
+      message.includes('wallet not connected') ||
+      message.includes('signature')
+    ) {
+      return ErrorCategory.AUTHORIZATION;
+    }
+
+    // Data errors
+    if (
+      message.includes('parse') ||
+      message.includes('json') ||
+      message.includes('data') ||
+      message.includes('supabase') ||
+      message.includes('database')
+    ) {
+      return ErrorCategory.DATA;
+    }
+
+    return ErrorCategory.UNKNOWN;
+  }
+
+  /**
+   * Get user-friendly error message
+   */
+  getErrorMessage(error: Error): string {
+    const category = this.classifyError(error);
+    const message = error.message;
+
+    switch (category) {
+      case ErrorCategory.NETWORK:
+        if (message.includes('timeout')) {
+          return 'Connection timeout. Please check your internet connection and try again.';
+        }
+        if (message.includes('rpc')) {
+          return 'Blockchain connection failed. Please try again in a moment.';
+        }
+        return 'Network error. Please check your connection and try again.';
+
+      case ErrorCategory.BLOCKCHAIN:
+        if (message.includes('insufficient')) {
+          return 'Insufficient balance. Please add more tokens to your wallet.';
+        }
+        if (message.includes('user rejected')) {
+          return 'Transaction cancelled.';
+        }
+        if (message.includes('slippage')) {
+          return 'Transaction failed due to price movement. Please try again.';
+        }
+        if (message.includes('simulation')) {
+          return 'Transaction simulation failed. Please check your inputs and try again.';
+        }
+        return 'Transaction failed. Please try again or contact support if the issue persists.';
+
+      case ErrorCategory.VALIDATION:
+        return message || 'Invalid input. Please check your values and try again.';
+
+      case ErrorCategory.AUTHORIZATION:
+        if (message.includes('wallet not connected')) {
+          return 'Please connect your wallet to continue.';
+        }
+        if (message.includes('unauthorized')) {
+          return 'You do not have permission to perform this action.';
+        }
+        return 'Authorization required. Please connect your wallet.';
+
+      case ErrorCategory.DATA:
+        return 'Data error. Please refresh the page and try again.';
+
+      default:
+        return message || 'An unexpected error occurred. Please try again.';
+    }
+  }
+
+  /**
+   * Get recovery suggestion based on error category
+   */
+  getRecoverySuggestion(error: Error): string | null {
+    const category = this.classifyError(error);
+
+    switch (category) {
+      case ErrorCategory.NETWORK:
+        return 'Check your internet connection and try again. If the problem persists, try refreshing the page.';
+
+      case ErrorCategory.BLOCKCHAIN:
+        return 'Verify your wallet has sufficient balance and try again. If the issue continues, check the transaction on Solana Explorer.';
+
+      case ErrorCategory.VALIDATION:
+        return 'Please review your inputs and ensure all required fields are filled correctly.';
+
+      case ErrorCategory.AUTHORIZATION:
+        return 'Please connect your wallet and ensure you have the necessary permissions.';
+
+      case ErrorCategory.DATA:
+        return 'Try refreshing the page. If the problem persists, contact support.';
+
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * Log error with context
+   */
+  logError(
+    error: Error,
+    context: string,
+    metadata?: Record<string, any>
+  ): void {
+    const category = this.classifyError(error);
+    const errorLog: ErrorLog = {
+      timestamp: Date.now(),
+      level: 'error',
+      context,
+      message: error.message,
+      stack: error.stack,
+      metadata,
+      userId: this.getCurrentUserId(),
+      category,
+    };
+
+    // Add to in-memory log
+    this.logs.push(errorLog);
+    if (this.logs.length > this.maxLogs) {
+      this.logs.shift();
+    }
+
+    // Log to console in development
+    if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'development') {
+      console.error(`[${context}]`, error, metadata);
+    }
+
+    // Send to monitoring service in production
+    if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'production') {
+      this.sendToMonitoring(errorLog);
+    }
+  }
+
+  /**
+   * Wrap async function with error handling and retry logic
+   */
+  async wrapAsync<T>(
+    fn: () => Promise<T>,
+    config?: ErrorHandlerConfig
+  ): Promise<T> {
+    const {
+      retryAttempts = 3,
+      retryDelay = 1000,
+      exponentialBackoff = true,
+      onRetry,
+    } = config || {};
+
+    let lastError: Error;
+    let attempt = 0;
+
+    while (attempt < retryAttempts) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error as Error;
+        attempt++;
+
+        // Don't retry validation errors
+        if (this.classifyError(lastError) === ErrorCategory.VALIDATION) {
+          throw lastError;
+        }
+
+        // Don't retry on final attempt
+        if (attempt >= retryAttempts) {
+          break;
+        }
+
+        // Calculate delay with exponential backoff
+        const delay = exponentialBackoff
+          ? retryDelay * Math.pow(2, attempt - 1)
+          : retryDelay;
+
+        // Add jitter to prevent thundering herd
+        const jitter = Math.random() * 500;
+
+        // Call retry callback
+        if (onRetry) {
+          onRetry(attempt, lastError);
+        }
+
+        await new Promise((resolve) => setTimeout(resolve, delay + jitter));
+      }
+    }
+
+    throw lastError!;
+  }
+
+  /**
+   * Handle error with appropriate recovery strategy
+   */
+  handleError(
+    error: Error,
+    context: string,
+    config?: ErrorHandlerConfig
+  ): void {
+    this.logError(error, context);
+
+    const category = this.classifyError(error);
+    const message = this.getErrorMessage(error);
+    const suggestion = this.getRecoverySuggestion(error);
+
+    // In a real implementation, this would trigger toast notifications
+    // For now, we'll just log it
+    console.error(`[${context}] ${message}`, suggestion ? `Suggestion: ${suggestion}` : '');
+  }
+
+  /**
+   * Get recent errors for debugging
+   */
+  getRecentErrors(count: number = 10): ErrorLog[] {
+    return this.logs.slice(-count);
+  }
+
+  /**
+   * Clear error logs
+   */
+  clearLogs(): void {
+    this.logs = [];
+  }
+
+  /**
+   * Get current user ID (if available)
+   */
+  private getCurrentUserId(): string | undefined {
+    // In a real implementation, this would get the current user's public key
+    if (typeof window !== 'undefined') {
+      // Could get from wallet connection state
+      return undefined;
+    }
+    return undefined;
+  }
+
+  /**
+   * Send error to monitoring service
+   */
+  private async sendToMonitoring(errorLog: ErrorLog): Promise<void> {
+    // In production, send to monitoring service (e.g., Sentry, LogRocket)
+    // For now, we'll just store it locally
+    try {
+      // Could send to Supabase or external service
+      // await supabase.from('error_logs').insert(errorLog);
+    } catch (e) {
+      console.error('Failed to send error to monitoring:', e);
+    }
+  }
+}
+
+// Export singleton instance
+export const errorHandler = new ErrorHandler();

package/src/utils/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Utils Index
+ * Export all utility functions
+ */
+
+export * from './errorHandler';
+export * from './cacheManager';
+export * from './tokenUtils';
+export * from './validation';
+export * from './toastService';
+export * from './rpcRetry';
+export * from './performanceMonitor';