@memberjunction/react-runtime 2.75.0 → 2.77.0

package/src/utilities/cache-manager.ts

@@ -0,0 +1,253 @@
+/**
+ * @fileoverview Cache management with TTL and size limits
+ * @module @memberjunction/react-runtime/utilities
+ */
+
+export interface CacheEntry<T> {
+  value: T;
+  timestamp: number;
+  size?: number;
+}
+
+export interface CacheOptions {
+  maxSize?: number;          // Maximum number of entries
+  maxMemory?: number;        // Maximum memory in bytes (estimated)
+  defaultTTL?: number;       // Default TTL in milliseconds
+  cleanupInterval?: number;  // Cleanup interval in milliseconds
+}
+
+/**
+ * Cache manager with TTL and size limits.
+ * Provides automatic cleanup and memory management.
+ */
+export class CacheManager<T = any> {
+  private cache = new Map<string, CacheEntry<T>>();
+  private memoryUsage = 0;
+  private cleanupTimer?: number;
+  private readonly options: Required<CacheOptions>;
+
+  constructor(options: CacheOptions = {}) {
+    this.options = {
+      maxSize: options.maxSize || 1000,
+      maxMemory: options.maxMemory || 50 * 1024 * 1024, // 50MB default
+      defaultTTL: options.defaultTTL || 5 * 60 * 1000,   // 5 minutes default
+      cleanupInterval: options.cleanupInterval || 60 * 1000 // 1 minute default
+    };
+
+    if (this.options.cleanupInterval > 0) {
+      this.startCleanupTimer();
+    }
+  }
+
+  /**
+   * Set a value in the cache
+   */
+  set(key: string, value: T, ttl?: number): void {
+    const size = this.estimateSize(value);
+    const entry: CacheEntry<T> = {
+      value,
+      timestamp: Date.now(),
+      size
+    };
+
+    // Check if we need to evict entries
+    if (this.cache.size >= this.options.maxSize) {
+      this.evictLRU();
+    }
+
+    // Check memory usage
+    if (this.memoryUsage + size > this.options.maxMemory) {
+      this.evictByMemory(size);
+    }
+
+    // Remove old entry if exists
+    const oldEntry = this.cache.get(key);
+    if (oldEntry) {
+      this.memoryUsage -= oldEntry.size || 0;
+    }
+
+    this.cache.set(key, entry);
+    this.memoryUsage += size;
+
+    // Schedule removal if TTL is set
+    if (ttl || this.options.defaultTTL) {
+      const timeout = ttl || this.options.defaultTTL;
+      setTimeout(() => this.delete(key), timeout);
+    }
+  }
+
+  /**
+   * Get a value from the cache
+   */
+  get(key: string): T | undefined {
+    const entry = this.cache.get(key);
+    if (!entry) return undefined;
+
+    // Check if expired
+    if (this.isExpired(entry)) {
+      this.delete(key);
+      return undefined;
+    }
+
+    // Update timestamp for LRU
+    entry.timestamp = Date.now();
+    return entry.value;
+  }
+
+  /**
+   * Check if a key exists and is not expired
+   */
+  has(key: string): boolean {
+    const entry = this.cache.get(key);
+    if (!entry) return false;
+
+    if (this.isExpired(entry)) {
+      this.delete(key);
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Delete a key from the cache
+   */
+  delete(key: string): boolean {
+    const entry = this.cache.get(key);
+    if (entry) {
+      this.memoryUsage -= entry.size || 0;
+      return this.cache.delete(key);
+    }
+    return false;
+  }
+
+  /**
+   * Clear all entries
+   */
+  clear(): void {
+    this.cache.clear();
+    this.memoryUsage = 0;
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): {
+    size: number;
+    memoryUsage: number;
+    maxSize: number;
+    maxMemory: number;
+  } {
+    return {
+      size: this.cache.size,
+      memoryUsage: this.memoryUsage,
+      maxSize: this.options.maxSize,
+      maxMemory: this.options.maxMemory
+    };
+  }
+
+  /**
+   * Manually trigger cleanup
+   */
+  cleanup(): number {
+    let removed = 0;
+    const now = Date.now();
+
+    for (const [key, entry] of this.cache) {
+      if (this.isExpired(entry, now)) {
+        this.delete(key);
+        removed++;
+      }
+    }
+
+    return removed;
+  }
+
+  /**
+   * Destroy the cache and stop cleanup timer
+   */
+  destroy(): void {
+    this.stopCleanupTimer();
+    this.clear();
+  }
+
+  /**
+   * Check if an entry is expired
+   */
+  private isExpired(entry: CacheEntry<T>, now?: number): boolean {
+    if (!this.options.defaultTTL) return false;
+    const currentTime = now || Date.now();
+    return currentTime - entry.timestamp > this.options.defaultTTL;
+  }
+
+  /**
+   * Evict least recently used entry
+   */
+  private evictLRU(): void {
+    let lruKey: string | undefined;
+    let lruTime = Infinity;
+
+    for (const [key, entry] of this.cache) {
+      if (entry.timestamp < lruTime) {
+        lruTime = entry.timestamp;
+        lruKey = key;
+      }
+    }
+
+    if (lruKey) {
+      this.delete(lruKey);
+    }
+  }
+
+  /**
+   * Evict entries to make room for new memory
+   */
+  private evictByMemory(requiredSize: number): void {
+    const entries = Array.from(this.cache.entries())
+      .sort((a, b) => a[1].timestamp - b[1].timestamp);
+
+    let freedMemory = 0;
+    for (const [key, entry] of entries) {
+      if (freedMemory >= requiredSize) break;
+      freedMemory += entry.size || 0;
+      this.delete(key);
+    }
+  }
+
+  /**
+   * Estimate size of a value
+   */
+  private estimateSize(value: T): number {
+    if (typeof value === 'string') {
+      return value.length * 2; // 2 bytes per character
+    } else if (typeof value === 'object' && value !== null) {
+      // Rough estimation for objects
+      try {
+        return JSON.stringify(value).length * 2;
+      } catch {
+        return 1024; // Default 1KB for objects that can't be stringified
+      }
+    } else {
+      return 8; // Default for primitives
+    }
+  }
+
+  /**
+   * Start the cleanup timer
+   */
+  private startCleanupTimer(): void {
+    this.cleanupTimer = window.setInterval(() => {
+      this.cleanup();
+    }, this.options.cleanupInterval);
+  }
+
+  /**
+   * Stop the cleanup timer
+   */
+  private stopCleanupTimer(): void {
+    if (this.cleanupTimer) {
+      window.clearInterval(this.cleanupTimer);
+      this.cleanupTimer = undefined;
+    }
+  }
+}

package/src/utilities/core-libraries.ts

@@ -0,0 +1,61 @@
+import { ExternalLibraryConfig } from '../types/library-config';
+
+/**
+ * Core runtime libraries required for the React runtime to function.
+ * These are not plugin libraries and are always loaded.
+ */
+export const CORE_RUNTIME_LIBRARIES: ExternalLibraryConfig[] = [
+  {
+    id: 'react',
+    name: 'react',
+    displayName: 'React',
+    category: 'runtime',
+    globalVariable: 'React',
+    version: '18.2.0',
+    cdnUrl: 'https://unpkg.com/react@18.2.0/umd/react.production.min.js',
+    description: 'React core library',
+    isEnabled: true,
+    isCore: true,
+    isRuntimeOnly: true
+  },
+  {
+    id: 'react-dom',
+    name: 'react-dom',
+    displayName: 'ReactDOM',
+    category: 'runtime',
+    globalVariable: 'ReactDOM',
+    version: '18.2.0',
+    cdnUrl: 'https://unpkg.com/react-dom@18.2.0/umd/react-dom.production.min.js',
+    description: 'React DOM library',
+    isEnabled: true,
+    isCore: true,
+    isRuntimeOnly: true
+  },
+  {
+    id: 'babel-standalone',
+    name: '@babel/standalone',
+    displayName: 'Babel Standalone',
+    category: 'runtime',
+    globalVariable: 'Babel',
+    version: '7.24.4',
+    cdnUrl: 'https://unpkg.com/@babel/standalone@7.24.4/babel.min.js',
+    description: 'Babel compiler for JSX transformation',
+    isEnabled: true,
+    isCore: true,
+    isRuntimeOnly: true
+  }
+];
+
+/**
+ * Get the core runtime libraries configuration
+ */
+export function getCoreRuntimeLibraries(): ExternalLibraryConfig[] {
+  return CORE_RUNTIME_LIBRARIES;
+}
+
+/**
+ * Check if a library ID is a core runtime library
+ */
+export function isCoreRuntimeLibrary(libraryId: string): boolean {
+  return CORE_RUNTIME_LIBRARIES.some(lib => lib.id === libraryId);
+}

package/src/utilities/index.ts

@@ -7,4 +7,6 @@ export * from './runtime-utilities';
 export * from './component-styles';
 export * from './standard-libraries';
 export * from './library-loader';
-export * from './component-error-analyzer';
+export * from './component-error-analyzer';
+export * from './resource-manager';
+export * from './cache-manager';

package/src/utilities/library-loader.ts

@@ -9,6 +9,11 @@ import {
   StandardLibraryManager
 } from './standard-libraries';
 import { LibraryConfiguration, ExternalLibraryConfig, LibraryLoadOptions as ConfigLoadOptions } from '../types/library-config';
+import { getCoreRuntimeLibraries, isCoreRuntimeLibrary } from './core-libraries';
+import { resourceManager } from './resource-manager';
+
+// Unique component ID for resource tracking
+const LIBRARY_LOADER_COMPONENT_ID = 'mj-react-runtime-library-loader-singleton';
 
 /**
  * Represents a loaded script or CSS resource
@@ -52,12 +57,30 @@ export class LibraryLoader {
   /**
    * Load all standard libraries (core + UI + CSS)
    * This is the main method that should be used by test harness and Angular wrapper
+   * @param config Optional full library configuration to replace the default
+   * @param additionalLibraries Optional additional libraries to merge with the configuration
    */
-  static async loadAllLibraries(config?: LibraryConfiguration): Promise<LibraryLoadResult> {
+  static async loadAllLibraries(
+    config?: LibraryConfiguration, 
+    additionalLibraries?: ExternalLibraryConfig[]
+  ): Promise<LibraryLoadResult> {
     if (config) {
       StandardLibraryManager.setConfiguration(config);
     }
     
+    // If additional libraries are provided, merge them with the current configuration
+    if (additionalLibraries && additionalLibraries.length > 0) {
+      const currentConfig = StandardLibraryManager.getConfiguration();
+      const mergedConfig: LibraryConfiguration = {
+        libraries: [...currentConfig.libraries, ...additionalLibraries],
+        metadata: {
+          ...currentConfig.metadata,
+          lastUpdated: new Date().toISOString()
+        }
+      };
+      StandardLibraryManager.setConfiguration(mergedConfig);
+    }
+    
     return this.loadLibrariesFromConfig();
   }
 
@@ -65,55 +88,55 @@ export class LibraryLoader {
    * Load libraries based on the current configuration
    */
   static async loadLibrariesFromConfig(options?: ConfigLoadOptions): Promise<LibraryLoadResult> {
+    // Always load core runtime libraries first
+    const coreLibraries = getCoreRuntimeLibraries();
+    const corePromises = coreLibraries.map(lib => 
+      this.loadScript(lib.cdnUrl, lib.globalVariable)
+    );
+    
+    const coreResults = await Promise.all(corePromises);
+    const React = coreResults.find((_, i) => coreLibraries[i].globalVariable === 'React');
+    const ReactDOM = coreResults.find((_, i) => coreLibraries[i].globalVariable === 'ReactDOM');
+    const Babel = coreResults.find((_, i) => coreLibraries[i].globalVariable === 'Babel');
+    
+    // Now load plugin libraries from configuration
     const config = StandardLibraryManager.getConfiguration();
     const enabledLibraries = StandardLibraryManager.getEnabledLibraries();
     
+    // Filter out any core runtime libraries from plugin configuration
+    let pluginLibraries = enabledLibraries.filter(lib => !isCoreRuntimeLibrary(lib.id));
+    
     // Apply options filters if provided
-    let librariesToLoad = enabledLibraries;
     if (options) {
       if (options.categories) {
-        librariesToLoad = librariesToLoad.filter(lib => 
+        pluginLibraries = pluginLibraries.filter(lib => 
           options.categories!.includes(lib.category)
         );
       }
       if (options.excludeRuntimeOnly) {
-        librariesToLoad = librariesToLoad.filter(lib => !lib.isRuntimeOnly);
+        pluginLibraries = pluginLibraries.filter(lib => !lib.isRuntimeOnly);
       }
     }
     
-    // Separate runtime and component libraries
-    const runtimeLibs = librariesToLoad.filter(lib => lib.category === 'runtime');
-    const componentLibs = librariesToLoad.filter(lib => lib.category !== 'runtime');
-    
-    // Load runtime libraries first (React, ReactDOM, Babel)
-    const runtimePromises = runtimeLibs.map(lib => 
-      this.loadScript(lib.cdnUrl, lib.globalVariable)
-    );
-    
-    const runtimeResults = await Promise.all(runtimePromises);
-    const React = runtimeResults.find((_, i) => runtimeLibs[i].globalVariable === 'React');
-    const ReactDOM = runtimeResults.find((_, i) => runtimeLibs[i].globalVariable === 'ReactDOM');
-    const Babel = runtimeResults.find((_, i) => runtimeLibs[i].globalVariable === 'Babel');
-    
-    // Load CSS files (non-blocking)
-    componentLibs.forEach(lib => {
+    // Load CSS files for plugin libraries (non-blocking)
+    pluginLibraries.forEach(lib => {
       if (lib.cdnCssUrl) {
         this.loadCSS(lib.cdnCssUrl);
       }
     });
     
-    // Load component libraries
-    const componentPromises = componentLibs.map(lib => 
+    // Load plugin libraries
+    const pluginPromises = pluginLibraries.map(lib => 
       this.loadScript(lib.cdnUrl, lib.globalVariable)
     );
     
-    const componentResults = await Promise.all(componentPromises);
+    const pluginResults = await Promise.all(pluginPromises);
     
-    // Build libraries object
+    // Build libraries object (only contains plugin libraries)
     const libraries: StandardLibraries = {};
     
-    componentLibs.forEach((lib, index) => {
-      libraries[lib.globalVariable] = componentResults[index];
+    pluginLibraries.forEach((lib, index) => {
+      libraries[lib.globalVariable] = pluginResults[index];
     });
     
     return {
@@ -195,28 +218,46 @@ export class LibraryLoader {
       script.async = true;
       script.crossOrigin = 'anonymous';
 
-      script.onload = () => {
+      const cleanup = () => {
+        script.removeEventListener('load', onLoad);
+        script.removeEventListener('error', onError);
+      };
+
+      const onLoad = () => {
+        cleanup();
         const global = (window as any)[globalName];
         if (global) {
           resolve(global);
         } else {
           // Some libraries may take a moment to initialize
-          setTimeout(() => {
-            const delayedGlobal = (window as any)[globalName];
-            if (delayedGlobal) {
-              resolve(delayedGlobal);
-            } else {
-              reject(new Error(`${globalName} not found after script load`));
-            }
-          }, 100);
+          const timeoutId = resourceManager.setTimeout(
+            LIBRARY_LOADER_COMPONENT_ID,
+            () => {
+              const delayedGlobal = (window as any)[globalName];
+              if (delayedGlobal) {
+                resolve(delayedGlobal);
+              } else {
+                reject(new Error(`${globalName} not found after script load`));
+              }
+            },
+            100,
+            { url, globalName }
+          );
         }
       };
 
-      script.onerror = () => {
+      const onError = () => {
+        cleanup();
         reject(new Error(`Failed to load script: ${url}`));
       };
 
+      script.addEventListener('load', onLoad);
+      script.addEventListener('error', onError);
+
       document.head.appendChild(script);
+      
+      // Register the script element for cleanup
+      resourceManager.registerDOMElement(LIBRARY_LOADER_COMPONENT_ID, script);
     });
 
     this.loadedResources.set(url, { 
@@ -244,6 +285,9 @@ export class LibraryLoader {
     link.rel = 'stylesheet';
     link.href = url;
     document.head.appendChild(link);
+    
+    // Register the link element for cleanup
+    resourceManager.registerDOMElement(LIBRARY_LOADER_COMPONENT_ID, link);
 
     this.loadedResources.set(url, {
       element: link,
@@ -266,14 +310,19 @@ export class LibraryLoader {
         resolve(global);
       } else {
         // Retry after a short delay
-        setTimeout(() => {
-          const delayedGlobal = (window as any)[globalName];
-          if (delayedGlobal) {
-            resolve(delayedGlobal);
-          } else {
-            reject(new Error(`${globalName} not found after script load`));
-          }
-        }, 100);
+        resourceManager.setTimeout(
+          LIBRARY_LOADER_COMPONENT_ID,
+          () => {
+            const delayedGlobal = (window as any)[globalName];
+            if (delayedGlobal) {
+              resolve(delayedGlobal);
+            } else {
+              reject(new Error(`${globalName} not found after script load`));
+            }
+          },
+          100,
+          { context: 'waitForScriptLoad', globalName }
+        );
       }
     };
 
@@ -285,10 +334,15 @@ export class LibraryLoader {
 
     // Wait for load
     const loadHandler = () => {
-      script.removeEventListener('load', loadHandler);
       checkGlobal();
     };
-    script.addEventListener('load', loadHandler);
+    resourceManager.addEventListener(
+      LIBRARY_LOADER_COMPONENT_ID,
+      script,
+      'load',
+      loadHandler,
+      { once: true }
+    );
   }
 
 
@@ -300,9 +354,19 @@ export class LibraryLoader {
   }
 
   /**
-   * Clear loaded resources cache
+   * Clear loaded resources cache and cleanup DOM elements
    */
   static clearCache(): void {
+    // Remove all script and link elements we added
+    this.loadedResources.forEach((resource, url) => {
+      if (resource.element && resource.element.parentNode) {
+        resource.element.parentNode.removeChild(resource.element);
+      }
+    });
+    
     this.loadedResources.clear();
+    
+    // Clean up any resources managed by resource manager
+    resourceManager.cleanupComponent(LIBRARY_LOADER_COMPONENT_ID);
   }
 }