@useavalon/avalon 0.1.13 → 0.1.14

package/src/islands/render-cache.ts

@@ -1,550 +0,0 @@
-/**
- * Island Render Cache Module
- * 
- * Provides caching for expensive operations in the island rendering pipeline:
- * - Component analysis results
- * - Resolved paths
- * - Framework detection results
- * 
- * This module helps optimize island rendering by avoiding repeated file I/O
- * and analysis operations for the same components.
- * 
- * @module render-cache
- */
-
-import type { AnalysisReport } from "../core/components/component-analyzer.ts";
-import type { Framework } from "./types.ts";
-
-/**
- * Cache entry for component analysis results
- */
-export interface AnalysisCacheEntry {
-  /** The analysis result */
-  result: AnalysisReport;
-  /** Timestamp when the entry was cached */
-  timestamp: number;
-}
-
-/**
- * Cache entry for resolved paths
- */
-export interface PathCacheEntry {
-  /** The resolved path */
-  resolved: string;
-  /** Timestamp when the entry was cached */
-  timestamp: number;
-}
-
-/**
- * Cache entry for framework detection results
- */
-export interface FrameworkCacheEntry {
-  /** The detected framework */
-  framework: Framework;
-  /** Timestamp when the entry was cached */
-  timestamp: number;
-}
-
-/**
- * Configuration options for the island render cache
- */
-export interface CacheConfig {
-  /** TTL for analysis cache entries in milliseconds (default: 60000ms = 1 minute) */
-  analysisTTL: number;
-  /** TTL for path cache entries in milliseconds (default: 60000ms = 1 minute) */
-  pathTTL: number;
-  /** TTL for framework cache entries in milliseconds (default: 60000ms = 1 minute) */
-  frameworkTTL: number;
-  /** Maximum number of entries per cache (default: 1000) */
-  maxEntries: number;
-}
-
-/**
- * Cache statistics for monitoring and debugging
- */
-export interface CacheStats {
-  /** Number of analysis cache entries */
-  analysisSize: number;
-  /** Number of path cache entries */
-  pathsSize: number;
-  /** Number of framework cache entries */
-  frameworksSize: number;
-  /** Number of cache hits for analysis */
-  analysisHits: number;
-  /** Number of cache misses for analysis */
-  analysisMisses: number;
-  /** Number of cache hits for paths */
-  pathHits: number;
-  /** Number of cache misses for paths */
-  pathMisses: number;
-  /** Number of cache hits for frameworks */
-  frameworkHits: number;
-  /** Number of cache misses for frameworks */
-  frameworkMisses: number;
-}
-
-/**
- * Island Render Cache interface
- * Centralized cache for all expensive operations in island rendering
- */
-export interface IslandRenderCache {
-  /** Analysis results by component path */
-  analysis: Map<string, AnalysisCacheEntry>;
-  /** Resolved paths by source path */
-  paths: Map<string, PathCacheEntry>;
-  /** Framework detection results by source path */
-  frameworks: Map<string, FrameworkCacheEntry>;
-  /** Cache configuration */
-  config: CacheConfig;
-  /** Cache statistics */
-  stats: CacheStats;
-}
-
-/**
- * Default cache configuration
- */
-const DEFAULT_CONFIG: CacheConfig = {
-  analysisTTL: 60000,    // 1 minute
-  pathTTL: 60000,        // 1 minute
-  frameworkTTL: 60000,   // 1 minute
-  maxEntries: 1000,
-};
-
-/**
- * Initial cache statistics
- */
-const INITIAL_STATS: CacheStats = {
-  analysisSize: 0,
-  pathsSize: 0,
-  frameworksSize: 0,
-  analysisHits: 0,
-  analysisMisses: 0,
-  pathHits: 0,
-  pathMisses: 0,
-  frameworkHits: 0,
-  frameworkMisses: 0,
-};
-
-/**
- * Global cache instance
- */
-const islandCache: IslandRenderCache = {
-  analysis: new Map(),
-  paths: new Map(),
-  frameworks: new Map(),
-  config: { ...DEFAULT_CONFIG },
-  stats: { ...INITIAL_STATS },
-};
-
-/**
- * Check if we're in development mode
- */
-function isDev(): boolean {
-  try {
-    return process.env.NODE_ENV !== "production";
-  } catch {
-    return true; // Default to dev mode if we can't check
-  }
-}
-
-function isVerbose(): boolean {
-  try {
-    return process.env.AVALON_VERBOSE === "1";
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Check if a cache entry is expired
- */
-function isExpired(timestamp: number, ttl: number): boolean {
-  return Date.now() - timestamp > ttl;
-}
-
-/**
- * Enforce max entries limit by removing oldest entries
- */
-function enforceMaxEntries<T>(cache: Map<string, T & { timestamp: number }>, maxEntries: number): void {
-  if (cache.size <= maxEntries) return;
-  
-  // Sort entries by timestamp and remove oldest
-  const entries = Array.from(cache.entries())
-    .sort((a, b) => a[1].timestamp - b[1].timestamp);
-  
-  const toRemove = entries.slice(0, cache.size - maxEntries);
-  for (const [key] of toRemove) {
-    cache.delete(key);
-  }
-}
-
-// ============================================================================
-// Analysis Cache Functions
-// ============================================================================
-
-/**
- * Get cached analysis result for a component path
- * 
- * @param src - The component source path
- * @returns The cached analysis result or null if not found/expired
- */
-export function getCachedAnalysis(src: string): AnalysisReport | null {
-  const cached = islandCache.analysis.get(src);
-  
-  if (cached) {
-    if (!isExpired(cached.timestamp, islandCache.config.analysisTTL)) {
-      islandCache.stats.analysisHits++;
-      return cached.result;
-    }
-    // Expired, remove from cache
-    islandCache.analysis.delete(src);
-  }
-  
-  islandCache.stats.analysisMisses++;
-  return null;
-}
-
-/**
- * Store analysis result in cache
- * 
- * @param src - The component source path
- * @param result - The analysis result to cache
- */
-export function setCachedAnalysis(src: string, result: AnalysisReport): void {
-  islandCache.analysis.set(src, {
-    result,
-    timestamp: Date.now(),
-  });
-  
-  islandCache.stats.analysisSize = islandCache.analysis.size;
-  enforceMaxEntries(islandCache.analysis, islandCache.config.maxEntries);
-}
-
-// ============================================================================
-// Path Cache Functions
-// ============================================================================
-
-/**
- * Get cached resolved path for a source path
- * 
- * @param src - The source path
- * @returns The cached resolved path or null if not found/expired
- */
-export function getCachedPath(src: string): string | null {
-  const cached = islandCache.paths.get(src);
-  
-  if (cached) {
-    if (!isExpired(cached.timestamp, islandCache.config.pathTTL)) {
-      islandCache.stats.pathHits++;
-      return cached.resolved;
-    }
-    // Expired, remove from cache
-    islandCache.paths.delete(src);
-  }
-  
-  islandCache.stats.pathMisses++;
-  return null;
-}
-
-/**
- * Store resolved path in cache
- * 
- * @param src - The source path
- * @param resolved - The resolved path to cache
- */
-export function setCachedPath(src: string, resolved: string): void {
-  islandCache.paths.set(src, {
-    resolved,
-    timestamp: Date.now(),
-  });
-  
-  islandCache.stats.pathsSize = islandCache.paths.size;
-  enforceMaxEntries(islandCache.paths, islandCache.config.maxEntries);
-}
-
-// ============================================================================
-// Framework Cache Functions
-// ============================================================================
-
-/**
- * Get cached framework detection result for a source path
- * 
- * @param src - The source path
- * @returns The cached framework or null if not found/expired
- */
-export function getCachedFramework(src: string): Framework | null {
-  const cached = islandCache.frameworks.get(src);
-  
-  if (cached) {
-    if (!isExpired(cached.timestamp, islandCache.config.frameworkTTL)) {
-      islandCache.stats.frameworkHits++;
-      return cached.framework;
-    }
-    // Expired, remove from cache
-    islandCache.frameworks.delete(src);
-  }
-  
-  islandCache.stats.frameworkMisses++;
-  return null;
-}
-
-/**
- * Store framework detection result in cache
- * 
- * @param src - The source path
- * @param framework - The detected framework to cache
- */
-export function setCachedFramework(src: string, framework: Framework): void {
-  islandCache.frameworks.set(src, {
-    framework,
-    timestamp: Date.now(),
-  });
-  
-  islandCache.stats.frameworksSize = islandCache.frameworks.size;
-  enforceMaxEntries(islandCache.frameworks, islandCache.config.maxEntries);
-}
-
-// ============================================================================
-// Cache Management Functions
-// ============================================================================
-
-/**
- * Clear all caches
- * Useful for testing or when file structure changes
- */
-export function clearCache(): void {
-  islandCache.analysis.clear();
-  islandCache.paths.clear();
-  islandCache.frameworks.clear();
-  
-  // Reset stats
-  islandCache.stats = { ...INITIAL_STATS };
-}
-
-/**
- * Clear cache for a specific component path
- * Useful for HMR when a specific file changes
- * 
- * @param src - The component source path to invalidate
- */
-export function invalidateCacheForPath(src: string): void {
-  islandCache.analysis.delete(src);
-  islandCache.paths.delete(src);
-  islandCache.frameworks.delete(src);
-  
-  // Update sizes
-  islandCache.stats.analysisSize = islandCache.analysis.size;
-  islandCache.stats.pathsSize = islandCache.paths.size;
-  islandCache.stats.frameworksSize = islandCache.frameworks.size;
-}
-
-/**
- * Configure cache settings
- * 
- * @param config - Partial configuration to merge with defaults
- */
-export function configureCache(config: Partial<CacheConfig>): void {
-  islandCache.config = {
-    ...islandCache.config,
-    ...config,
-  };
-}
-
-/**
- * Get current cache configuration
- * 
- * @returns The current cache configuration
- */
-export function getCacheConfig(): CacheConfig {
-  return { ...islandCache.config };
-}
-
-/**
- * Get cache statistics for monitoring and debugging
- * Only logs in development mode
- * 
- * @returns Current cache statistics
- */
-export function getCacheStats(): CacheStats {
-  return {
-    analysisSize: islandCache.analysis.size,
-    pathsSize: islandCache.paths.size,
-    frameworksSize: islandCache.frameworks.size,
-    analysisHits: islandCache.stats.analysisHits,
-    analysisMisses: islandCache.stats.analysisMisses,
-    pathHits: islandCache.stats.pathHits,
-    pathMisses: islandCache.stats.pathMisses,
-    frameworkHits: islandCache.stats.frameworkHits,
-    frameworkMisses: islandCache.stats.frameworkMisses,
-  };
-}
-
-/**
- * Log cache statistics to console (dev mode only)
- * Useful for debugging and performance monitoring
- */
-export function logCacheStats(): void {
-  if (!isDev() || !isVerbose()) return;
-  
-  const stats = getCacheStats();
-  const totalHits = stats.analysisHits + stats.pathHits + stats.frameworkHits;
-  const totalMisses = stats.analysisMisses + stats.pathMisses + stats.frameworkMisses;
-  const hitRate = totalHits + totalMisses > 0 
-    ? ((totalHits / (totalHits + totalMisses)) * 100).toFixed(1) 
-    : "0.0";
-  
-  console.log("📊 Island Render Cache Stats:");
-  console.log(`   Analysis: ${stats.analysisSize} entries (${stats.analysisHits} hits / ${stats.analysisMisses} misses)`);
-  console.log(`   Paths: ${stats.pathsSize} entries (${stats.pathHits} hits / ${stats.pathMisses} misses)`);
-  console.log(`   Frameworks: ${stats.frameworksSize} entries (${stats.frameworkHits} hits / ${stats.frameworkMisses} misses)`);
-  console.log(`   Overall hit rate: ${hitRate}%`);
-}
-
-/**
- * Get the raw cache instance (for testing purposes only)
- * @internal
- */
-export function _getCache(): IslandRenderCache {
-  return islandCache;
-}
-
-// ============================================================================
-// File Watcher Integration Functions
-// ============================================================================
-
-/**
- * Normalize a file path for cache key matching
- * Handles various path formats from Vite file watcher
- * 
- * @param filePath - The file path to normalize
- * @returns Normalized path for cache key matching
- */
-function normalizePathForCache(filePath: string): string {
-  return filePath
-    .replace(/\\/g, '/')  // Normalize Windows paths
-    .replace(/^\//, '')   // Remove leading slash
-    .replace(/\?.*$/, '') // Remove query strings
-    .replace(/#.*$/, ''); // Remove hash fragments
-}
-
-/**
- * Check if a file path matches any cached entry
- * Uses partial matching to handle different path formats
- * 
- * @param filePath - The file path to check
- * @param cacheKey - The cache key to match against
- * @returns True if the paths match
- */
-function pathMatchesCacheKey(filePath: string, cacheKey: string): boolean {
-  const normalizedFile = normalizePathForCache(filePath);
-  const normalizedKey = normalizePathForCache(cacheKey);
-  
-  // Exact match
-  if (normalizedFile === normalizedKey) return true;
-  
-  // Partial match (file path ends with cache key or vice versa)
-  if (normalizedFile.endsWith(normalizedKey) || normalizedKey.endsWith(normalizedFile)) return true;
-  
-  // Filename match (for cases where full paths differ)
-  const fileName = normalizedFile.split('/').pop();
-  const keyFileName = normalizedKey.split('/').pop();
-  if (fileName && keyFileName && fileName === keyFileName) return true;
-  
-  return false;
-}
-
-/**
- * Invalidate cache entries for a specific file path
- * Called when a component file changes during development
- * 
- * @param filePath - The path of the changed file
- * @returns Number of cache entries invalidated
- */
-export function invalidateCacheForFile(filePath: string): number {
-  let invalidatedCount = 0;
-  
-  // Find and remove matching entries from analysis cache
-  for (const key of islandCache.analysis.keys()) {
-    if (pathMatchesCacheKey(filePath, key)) {
-      islandCache.analysis.delete(key);
-      invalidatedCount++;
-      if (isVerbose()) {
-        console.log(`🗑️ [Cache] Invalidated analysis cache for: ${key}`);
-      }
-    }
-  }
-  
-  // Find and remove matching entries from paths cache
-  for (const key of islandCache.paths.keys()) {
-    if (pathMatchesCacheKey(filePath, key)) {
-      islandCache.paths.delete(key);
-      invalidatedCount++;
-      if (isVerbose()) {
-        console.log(`🗑️ [Cache] Invalidated path cache for: ${key}`);
-      }
-    }
-  }
-  
-  // Find and remove matching entries from frameworks cache
-  for (const key of islandCache.frameworks.keys()) {
-    if (pathMatchesCacheKey(filePath, key)) {
-      islandCache.frameworks.delete(key);
-      invalidatedCount++;
-      if (isVerbose()) {
-        console.log(`🗑️ [Cache] Invalidated framework cache for: ${key}`);
-      }
-    }
-  }
-  
-  // Update stats
-  islandCache.stats.analysisSize = islandCache.analysis.size;
-  islandCache.stats.pathsSize = islandCache.paths.size;
-  islandCache.stats.frameworksSize = islandCache.frameworks.size;
-  
-  return invalidatedCount;
-}
-
-/**
- * Check if a file path is an island component file
- * Used to determine if cache invalidation is needed
- * 
- * @param filePath - The file path to check
- * @returns True if the file is an island component
- */
-export function isIslandComponentFile(filePath: string): boolean {
-  const normalized = normalizePathForCache(filePath);
-  
-  // Check if it's in an islands directory
-  if (normalized.includes('/islands/') || normalized.includes('\\islands\\')) {
-    return true;
-  }
-  
-  // Check for common component file extensions
-  const componentExtensions = ['.tsx', '.jsx', '.vue', '.svelte', '.solid.tsx', '.lit.ts'];
-  return componentExtensions.some(ext => normalized.endsWith(ext));
-}
-
-/**
- * Clear all caches when file structure changes significantly
- * Called when files are added or removed
- */
-export function clearPathCacheOnStructureChange(): void {
-  islandCache.paths.clear();
-  islandCache.stats.pathsSize = 0;
-  
-  if (isVerbose()) {
-    console.log('🗑️ [Cache] Cleared path cache due to file structure change');
-  }
-}
-
-/**
- * Alias for clearCache - provides a more descriptive name for external use
- * Clears all island render caches
- */
-export function clearIslandCache(): void {
-  clearCache();
-  
-  if (isVerbose()) {
-    console.log('🗑️ [Cache] Cleared all island render caches');
-  }
-}

package/src/islands/types.ts

@@ -1,80 +0,0 @@
-import type { JSX } from "preact";
-import type { AnalyzerOptions } from "../core/components/component-analyzer.ts";
-
-/**
- * Framework type for island components
- * Represents the supported UI frameworks for island architecture
- */
-export type Framework =
-  | "solid"
-  | "vue"
-  | "svelte"
-  | "preact"
-  | "react"
-  | "lit"
-  | "qwik"
-  | "unknown";
-
-/**
- * Props for the Island component
- * Defines the configuration for rendering an interactive island component
- */
-export interface IslandProps {
-  /** Path to the island component (e.g., "/islands/Counter.tsx") */
-  src: string;
-  /** Hydration condition */
-  condition?:
-    | "on:visible"
-    | "on:interaction"
-    | "on:idle"
-    | "on:client"
-    | `media:${string}`;
-  /** Props to pass to the island component */
-  props?: Record<string, unknown>;
-  /** Children to render inside the island (for SSR) */
-  children?: JSX.Element | JSX.Element[] | string;
-  /** Whether to render server-side (default: true unless condition is 'on:client') */
-  ssr?: boolean;
-  /** Framework hint for client hydration */
-  framework?: "solid" | "vue" | "preact" | "react" | "svelte" | "lit" | "qwik";
-  /** Force SSR-only rendering without hydration */
-  ssrOnly?: boolean;
-  /** Component render options for intelligent detection */
-  renderOptions?: AnalyzerOptions;
-}
-
-/**
- * Parameters for framework-specific render functions
- * Used by all framework renderers to maintain consistent interface
- */
-export interface RenderParams {
-  /** Path to the island component */
-  src: string;
-  /** Hydration condition */
-  condition: IslandProps["condition"];
-  /** Props to pass to the component */
-  props: Record<string, unknown>;
-  /** Whether to render server-side */
-  ssr: boolean;
-  /** Component render options for intelligent detection */
-  renderOptions?: AnalyzerOptions;
-  /** Force SSR-only rendering without hydration */
-  ssrOnly?: boolean;
-}
-
-/**
- * Entry in the Svelte SSR CSS collection
- * Tracks CSS for Svelte components during server-side rendering
- */
-export interface SvelteSSRCSSEntry {
-  /** The CSS content */
-  css: string;
-  /** Unique scope identifier for the component */
-  scopeId: string;
-  /** Source path of the component */
-  src: string;
-  /** Whether this is global CSS */
-  isGlobal: boolean;
-  /** Timestamp when the CSS was added */
-  timestamp: number;
-}