@memberjunction/react-runtime 2.98.0 → 2.100.0

package/src/component-manager/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Unified Component Manager for MemberJunction React Runtime
+ * Consolidates component fetching, compilation, registration, and usage tracking
+ * into a single, efficient manager that eliminates duplicate operations.
+ */
+
+export { ComponentManager } from './component-manager';
+export type {
+  LoadOptions,
+  LoadResult,
+  HierarchyResult,
+  ComponentManagerConfig
+} from './types';

package/src/component-manager/types.ts

@@ -0,0 +1,204 @@
+/**
+ * @fileoverview Type definitions for the unified ComponentManager
+ */
+
+import { ComponentSpec } from '@memberjunction/interactive-component-types';
+import { UserInfo } from '@memberjunction/core';
+import { ComponentLibraryEntity } from '@memberjunction/core-entities';
+import { ComponentObject } from '../types';
+
+/**
+ * Resolution mode for specs
+ */
+export type ResolutionMode = 'embed' | 'preserve-metadata';
+
+/**
+ * Options for loading a component
+ */
+export interface LoadOptions {
+  /**
+   * User context for database operations and registry fetching
+   */
+  contextUser?: UserInfo;
+  
+  /**
+   * Force re-fetch from registry even if cached
+   */
+  forceRefresh?: boolean;
+  
+  /**
+   * Force recompilation even if compiled version exists
+   */
+  forceRecompile?: boolean;
+  
+  /**
+   * Whether this is a dependent component (for tracking)
+   */
+  isDependent?: boolean;
+  
+  /**
+   * What to return from the load operation
+   */
+  returnType?: 'component' | 'spec' | 'both';
+  
+  /**
+   * Enable registry usage tracking for licensing (default: true)
+   */
+  trackUsage?: boolean;
+  
+  /**
+   * Namespace to use if not specified in spec
+   */
+  defaultNamespace?: string;
+  
+  /**
+   * Version to use if not specified in spec
+   */
+  defaultVersion?: string;
+  
+  /**
+   * How to format resolved specs:
+   * - 'preserve-metadata': Keep registry/namespace/name intact (for UI display)
+   * - 'embed': Convert to embedded format (for test harness)
+   * @default 'preserve-metadata'
+   */
+  resolutionMode?: ResolutionMode;
+  
+  /**
+   * All available component libraries (for browser context where ComponentMetadataEngine isn't available)
+   */
+  allLibraries?: ComponentLibraryEntity[];
+}
+
+/**
+ * Result of loading a single component
+ */
+export interface LoadResult {
+  /**
+   * Whether the load operation succeeded
+   */
+  success: boolean;
+  
+  /**
+   * The compiled component object
+   */
+  component?: ComponentObject;
+  
+  /**
+   * The fully resolved component specification
+   */
+  spec?: ComponentSpec;
+  
+  /**
+   * Whether the component was loaded from cache
+   */
+  fromCache: boolean;
+  
+  /**
+   * Any errors that occurred during loading
+   */
+  errors?: Array<{
+    message: string;
+    phase: 'fetch' | 'compile' | 'register' | 'dependency';
+    componentName?: string;
+  }>;
+  
+  /**
+   * Components that were loaded as dependencies
+   */
+  dependencies?: Record<string, ComponentObject>;
+}
+
+/**
+ * Result of loading a component hierarchy
+ */
+export interface HierarchyResult {
+  /**
+   * Whether the entire hierarchy loaded successfully
+   */
+  success: boolean;
+  
+  /**
+   * The root component object
+   */
+  rootComponent?: ComponentObject;
+  
+  /**
+   * The fully resolved root specification
+   */
+  resolvedSpec?: ComponentSpec;
+  
+  /**
+   * List of all component names that were loaded
+   */
+  loadedComponents: string[];
+  
+  /**
+   * Any errors that occurred during loading
+   */
+  errors: Array<{
+    message: string;
+    phase: 'fetch' | 'compile' | 'register' | 'dependency';
+    componentName?: string;
+  }>;
+  
+  /**
+   * Map of all loaded components by name
+   */
+  components?: Record<string, ComponentObject>;
+  
+  /**
+   * Number of components loaded from cache vs fetched
+   */
+  stats?: {
+    fromCache: number;
+    fetched: number;
+    compiled: number;
+    totalTime: number;
+  };
+}
+
+/**
+ * Configuration for ComponentManager
+ */
+export interface ComponentManagerConfig {
+  /**
+   * Enable debug logging
+   */
+  debug?: boolean;
+  
+  /**
+   * Maximum cache size for fetched specs
+   */
+  maxCacheSize?: number;
+  
+  /**
+   * Cache TTL in milliseconds (default: 1 hour)
+   */
+  cacheTTL?: number;
+  
+  /**
+   * Whether to track registry usage for licensing
+   */
+  enableUsageTracking?: boolean;
+  
+  /**
+   * Batch size for parallel dependency loading
+   */
+  dependencyBatchSize?: number;
+  
+  /**
+   * Timeout for registry fetch operations (ms)
+   */
+  fetchTimeout?: number;
+}
+
+/**
+ * Internal cache entry for fetched specs
+ */
+export interface CacheEntry {
+  spec: ComponentSpec;
+  fetchedAt: Date;
+  hash?: string;
+  usageNotified: boolean;
+}

package/src/index.ts

@@ -8,6 +8,7 @@
 import { ComponentCompiler } from './compiler';
 import { ComponentRegistry } from './registry';
 import { ComponentResolver } from './registry';
+import { ComponentManager } from './component-manager';
 
 // Export all types
 export * from './types';
@@ -30,9 +31,19 @@ export {
   ComponentResolver,
   ComponentSpec,
   ResolvedComponents,
-  ComponentRegistryService
+  ComponentRegistryService,
+  IComponentRegistryClient
 } from './registry';
 
+// Export unified ComponentManager
+export { ComponentManager } from './component-manager';
+export type {
+  LoadOptions,
+  LoadResult,
+  HierarchyResult,
+  ComponentManagerConfig
+} from './component-manager';
+
 // Export runtime APIs
 export {
   createErrorBoundary,
@@ -117,6 +128,16 @@ export {
   CacheOptions
 } from './utilities/cache-manager';
 
+export {
+  unwrapLibraryComponent,
+  unwrapLibraryComponents,
+  unwrapAllLibraryComponents,
+  // Legacy exports for backward compatibility
+  unwrapComponent,
+  unwrapComponents,
+  unwrapAllComponents
+} from './utilities/component-unwrapper';
+
 // Version information
 export const VERSION = '2.69.1';
 
@@ -153,6 +174,7 @@ export function createReactRuntime(
   config?: {
     compiler?: Partial<import('./types').CompilerConfig>;
     registry?: Partial<import('./types').RegistryConfig>;
+    manager?: Partial<import('./component-manager').ComponentManagerConfig>;
   },
   runtimeContext?: import('./types').RuntimeContext,
   debug: boolean = false
@@ -168,16 +190,30 @@ export function createReactRuntime(
     debug: config?.registry?.debug ?? debug
   };
   
+  const managerConfig = {
+    ...config?.manager,
+    debug: config?.manager?.debug ?? debug
+  };
+  
   const compiler = new ComponentCompiler(compilerConfig);
   compiler.setBabelInstance(babelInstance);
   
   const registry = new ComponentRegistry(registryConfig);
   const resolver = new ComponentResolver(registry, compiler, runtimeContext);
+  
+  // Create the unified ComponentManager
+  const manager = new ComponentManager(
+    compiler,
+    registry,
+    runtimeContext || { React: null, ReactDOM: null },
+    managerConfig
+  );
 
   return {
     compiler,
     registry,
     resolver,
+    manager,  // New unified manager
     version: VERSION,
     debug
   };

package/src/registry/component-registry-service.ts

@@ -22,15 +22,36 @@ import {
   ComponentMetadataEngine
 } from '@memberjunction/core-entities';
 
+// Type-only import for TypeScript - won't be included in UMD bundle
+import type { GraphQLDataProvider } from '@memberjunction/graphql-dataprovider';
+
+// Dynamic import of GraphQLComponentRegistryClient to avoid breaking UMD build
+let GraphQLComponentRegistryClient: any;
+
+
 /**
  * Cached compiled component with metadata
  */
 interface CachedCompiledComponent {
-  component: ComponentObject;
+  component: (context: RuntimeContext, styles?: any, components?: Record<string, any>) => ComponentObject;
   metadata: RegistryComponentResponse['metadata'];
   compiledAt: Date;
   lastUsed: Date;
   useCount: number;
+  specHash?: string;  // SHA-256 hash of the spec used for compilation
+}
+
+/**
+ * GraphQL client interface for registry operations
+ */
+export interface IComponentRegistryClient {
+  GetRegistryComponent(params: {
+    registryName: string;
+    namespace: string;
+    name: string;
+    version?: string;
+    hash?: string;
+  }): Promise<ComponentSpec | null>;
 }
 
 /**
@@ -49,15 +70,18 @@ export class ComponentRegistryService {
   private componentEngine = ComponentMetadataEngine.Instance;
   private registryProviders = new Map<string, RegistryProvider>();
   private debug: boolean = false;
+  private graphQLClient?: IComponentRegistryClient;
   
   private constructor(
     compiler: ComponentCompiler,
     runtimeContext: RuntimeContext,
-    debug: boolean = false
+    debug: boolean = false,
+    graphQLClient?: IComponentRegistryClient
   ) {
     this.compiler = compiler;
     this.runtimeContext = runtimeContext;
     this.debug = debug;
+    this.graphQLClient = graphQLClient;
   }
   
   /**
@@ -66,14 +90,88 @@ export class ComponentRegistryService {
   static getInstance(
     compiler: ComponentCompiler, 
     context: RuntimeContext,
-    debug: boolean = false
+    debug: boolean = false,
+    graphQLClient?: IComponentRegistryClient
   ): ComponentRegistryService {
     if (!ComponentRegistryService.instance) {
-      ComponentRegistryService.instance = new ComponentRegistryService(compiler, context, debug);
+      ComponentRegistryService.instance = new ComponentRegistryService(compiler, context, debug, graphQLClient);
     }
     return ComponentRegistryService.instance;
   }
   
+  /**
+   * Set the GraphQL client for registry operations
+   */
+  setGraphQLClient(client: IComponentRegistryClient): void {
+    this.graphQLClient = client;
+    if (this.debug) {
+      console.log('✅ GraphQL client configured for component registry');
+    }
+  }
+  
+  /**
+   * Cached GraphQL client instance created from Metadata.Provider
+   */
+  private cachedProviderClient: IComponentRegistryClient | null = null;
+  
+  /**
+   * Get the GraphQL client, using the provided one or falling back to creating one with Metadata.Provider
+   * @returns The GraphQL client if available
+   */
+  private async getGraphQLClient(): Promise<IComponentRegistryClient | null> {
+    // If explicitly set, use that
+    if (this.graphQLClient) {
+      return this.graphQLClient;
+    }
+    
+    // If we've already created one from the provider, reuse it
+    if (this.cachedProviderClient) {
+      return this.cachedProviderClient;
+    }
+    
+    // Try to create GraphQLComponentRegistryClient with Metadata.Provider
+    try {
+      const provider = Metadata?.Provider;
+      if (provider && (provider as any).ExecuteGQL !== undefined) {
+        // Dynamically load GraphQLComponentRegistryClient if not already loaded
+        if (!GraphQLComponentRegistryClient) {
+          try {
+            const graphqlModule = await import('@memberjunction/graphql-dataprovider');
+            GraphQLComponentRegistryClient = graphqlModule.GraphQLComponentRegistryClient;
+          } catch (importError) {
+            if (this.debug) {
+              console.log('⚠️ [ComponentRegistryService] @memberjunction/graphql-dataprovider not available');
+            }
+            return null;
+          }
+        }
+        
+        // Create the client if we have the class
+        if (GraphQLComponentRegistryClient) {
+          try {
+            const client = new GraphQLComponentRegistryClient(provider as GraphQLDataProvider);
+            this.cachedProviderClient = client;
+            if (this.debug) {
+              console.log('📡 [ComponentRegistryService] Created GraphQL client from Metadata.Provider');
+            }
+            return client;
+          } catch (error) {
+            if (this.debug) {
+              console.log('⚠️ [ComponentRegistryService] Failed to create GraphQL client:', error);
+            }
+          }
+        }
+      }
+    } catch (error) {
+      // Provider might not be available in all environments
+      if (this.debug) {
+        console.log('⚠️ [ComponentRegistryService] Could not access Metadata.Provider:', error);
+      }
+    }
+    
+    return null;
+  }
+  
   /**
    * Initialize the service with metadata
    */
@@ -82,6 +180,34 @@ export class ComponentRegistryService {
     await this.componentEngine.Config(false, contextUser);
   }
   
+  /**
+   * Calculate SHA-256 hash of a component spec for cache comparison
+   * Uses Web Crypto API which is available in modern browsers and Node.js 15+
+   */
+  private async calculateSpecHash(spec: ComponentSpec): Promise<string> {
+    // Check for crypto.subtle availability
+    if (typeof crypto === 'undefined' || !crypto.subtle) {
+      throw new Error(
+        'Web Crypto API not available. This typically happens when running in an insecure context. ' +
+        'Please use HTTPS or localhost for development. ' +
+        'Note: crypto.subtle is available in Node.js 15+ and all modern browsers on secure contexts.'
+      );
+    }
+    
+    const specString = JSON.stringify(spec);
+    const encoder = new TextEncoder();
+    const data = encoder.encode(specString);
+    
+    // Calculate SHA-256 hash using Web Crypto API
+    const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+    
+    // Convert ArrayBuffer to hex string
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+    
+    return hashHex;
+  }
+  
   /**
    * Get a compiled component, using cache if available
    */
@@ -114,7 +240,8 @@ export class ComponentRegistryService {
       if (this.debug) {
         console.log(`✅ Reusing compiled component from cache: ${key} (use count: ${cached.useCount})`);
       }
-      return cached.component;
+      // Call the factory function to get the ComponentObject
+      return cached.component(this.runtimeContext);
     }
     
     // Not in cache, need to load and compile
@@ -169,9 +296,9 @@ export class ComponentRegistryService {
     if (!compilationResult.component) {
       throw new Error(`Component compilation succeeded but no component returned`);
     }
-    const compiledComponent = compilationResult.component.factory(this.runtimeContext);
+    const compiledComponentFactory = compilationResult.component.factory;
     this.compiledComponentCache.set(key, {
-      component: compiledComponent,
+      component: compiledComponentFactory,
       metadata,
       compiledAt: new Date(),
       lastUsed: new Date(),
@@ -183,7 +310,158 @@ export class ComponentRegistryService {
       this.addComponentReference(key, referenceId);
     }
     
-    return compiledComponent;
+    // Call the factory function to get the ComponentObject
+    return compiledComponentFactory(this.runtimeContext);
+  }
+  
+  /**
+   * Get compiled component from external registry by registry name
+   * This is used when spec.registry field is populated
+   */
+  async getCompiledComponentFromRegistry(
+    registryName: string,
+    namespace: string,
+    name: string,
+    version: string,
+    referenceId?: string,
+    contextUser?: UserInfo
+  ): Promise<any> {
+    await this.initialize(contextUser);
+    
+    if (this.debug) {
+      console.log(`🌐 [ComponentRegistryService] Fetching from external registry: ${registryName}/${namespace}/${name}@${version}`);
+    }
+    
+    // Find the registry by name in ComponentRegistries
+    const registry = this.componentEngine.ComponentRegistries?.find(
+      r => r.Name === registryName && r.Status === 'Active'
+    );
+    
+    if (!registry) {
+      throw new Error(`Registry not found or inactive: ${registryName}`);
+    }
+    
+    if (this.debug) {
+      console.log(`✅ [ComponentRegistryService] Found registry: ${registry.Name} (ID: ${registry.ID})`);
+    }
+    
+    // Get GraphQL client - use provided one or fallback to Metadata.Provider
+    const graphQLClient = await this.getGraphQLClient();
+    if (!graphQLClient) {
+      throw new Error('GraphQL client not available for external registry fetching. No client provided and Metadata.Provider is not a GraphQLDataProvider.');
+    }
+    
+    // Check if we have a cached version first
+    const key = `external:${registryName}:${namespace}:${name}:${version}`;
+    const cached = this.compiledComponentCache.get(key);
+    
+    try {
+      // Fetch component spec from external registry via MJServer
+      // Pass cached hash if available for efficient caching
+      const spec = await graphQLClient.GetRegistryComponent({
+        registryName: registry.Name,  // Pass registry name, not ID
+        namespace,
+        name,
+        version,
+        hash: cached?.specHash  // Pass cached hash if available
+      });
+      
+      // If null returned, it means not modified (304)
+      if (!spec && cached?.specHash) {
+        if (this.debug) {
+          console.log(`♻️ [ComponentRegistryService] Component not modified, using cached: ${key}`);
+        }
+        cached.lastUsed = new Date();
+        cached.useCount++;
+        
+        // Track reference
+        if (referenceId) {
+          this.addComponentReference(key, referenceId);
+        }
+        
+        // Call the factory function to get the ComponentObject
+        return cached.component(this.runtimeContext);
+      }
+      
+      if (!spec) {
+        throw new Error(`Component not found in registry ${registryName}: ${namespace}/${name}@${version}`);
+      }
+      
+      if (this.debug) {
+        console.log(`✅ [ComponentRegistryService] Fetched spec from external registry: ${spec.name}`);
+      }
+      
+      // Calculate hash of the fetched spec
+      const specHash = await this.calculateSpecHash(spec);
+      
+      // Check if hash matches cached version (shouldn't happen if server works correctly)
+      if (cached && cached.specHash === specHash) {
+        if (this.debug) {
+          console.log(`♻️ [ComponentRegistryService] Using cached compilation for: ${key} (hash match)`);
+        }
+        cached.lastUsed = new Date();
+        cached.useCount++;
+        
+        // Track reference
+        if (referenceId) {
+          this.addComponentReference(key, referenceId);
+        }
+        
+        // Call the factory function to get the ComponentObject
+        return cached.component(this.runtimeContext);
+      }
+      
+      // Spec has changed or is new, need to compile
+      if (cached && this.debug) {
+        console.log(`🔄 [ComponentRegistryService] Spec changed for: ${key}, recompiling (old hash: ${cached.specHash?.substring(0, 8)}..., new hash: ${specHash.substring(0, 8)}...)`);
+      }
+      
+      // Load all libraries from metadata engine
+      const allLibraries = this.componentEngine.ComponentLibraries || [];
+      
+      // Compile the component
+      const compilationResult = await this.compiler.compile({
+        componentName: spec.name,
+        componentCode: spec.code || '',
+        allLibraries: allLibraries
+      });
+      
+      if (!compilationResult.success || !compilationResult.component) {
+        throw new Error(`Failed to compile component: ${compilationResult.error?.message || 'Unknown error'}`);
+      }
+      
+      // Cache the compiled component with spec hash
+      this.compiledComponentCache.set(key, {
+        component: compilationResult.component.factory,
+        metadata: {
+          name: spec.name,
+          namespace: spec.namespace || '',
+          version: spec.version || '1.0.0',
+          description: spec.description || '',
+          type: spec.type,
+          isLocal: false  // This is from an external registry
+        },
+        compiledAt: new Date(),
+        lastUsed: new Date(),
+        useCount: 1,
+        specHash: specHash  // Store the hash for future comparison
+      });
+      
+      // Track reference
+      if (referenceId) {
+        this.addComponentReference(key, referenceId);
+      }
+      
+      if (this.debug) {
+        console.log(`🎯 [ComponentRegistryService] Successfully compiled external component: ${spec.name}`);
+      }
+      
+      // Call the factory function to get the ComponentObject
+      return compilationResult.component.factory(this.runtimeContext);
+    } catch (error) {
+      console.error(`❌ [ComponentRegistryService] Failed to fetch from external registry:`, error);
+      throw error;
+    }
   }
   
   /**
@@ -226,17 +504,36 @@ export class ComponentRegistryService {
       throw new Error(`Registry not found: ${component.SourceRegistryID}`);
     }
     
-    if (!registry) {
-      throw new Error(`Registry not found: ${component.SourceRegistryID}`);
-    }
+    // Try GraphQL client first if available
+    let spec: ComponentSpec;
     
-    const spec = await this.fetchFromExternalRegistry(
-      registry.URI || '',
-      component.Name,
-      component.Namespace || '',
-      component.Version,
-      this.getRegistryApiKey(registry.ID) // API keys stored in env vars or secure config
-    );
+    if (this.graphQLClient) {
+      if (this.debug) {
+        console.log(`Fetching from registry via GraphQL: ${component.Name}`);
+      }
+      
+      const result = await this.graphQLClient.GetRegistryComponent({
+        registryName: registry.Name,
+        namespace: component.Namespace || '',
+        name: component.Name,
+        version: component.Version
+      });
+      
+      if (!result) {
+        throw new Error(`Component not found in registry: ${component.Name}`);
+      }
+      
+      spec = result;
+    } else {
+      // Fallback to direct HTTP if no GraphQL client
+      spec = await this.fetchFromExternalRegistry(
+        registry.URI || '',
+        component.Name,
+        component.Namespace || '',
+        component.Version,
+        this.getRegistryApiKey(registry.ID)
+      );
+    }
     
     // Store in local database for future use
     await this.cacheExternalComponent(componentId, spec, contextUser);