@memberjunction/react-runtime 2.70.0

package/src/registry/component-registry.ts

@@ -0,0 +1,379 @@
+/**
+ * @fileoverview Platform-agnostic component registry for managing compiled React components.
+ * Provides storage, retrieval, and lifecycle management for components with namespace support.
+ * @module @memberjunction/react-runtime/registry
+ */
+
+import { 
+  RegistryEntry, 
+  ComponentMetadata, 
+  RegistryConfig 
+} from '../types';
+
+/**
+ * Default registry configuration
+ */
+const DEFAULT_REGISTRY_CONFIG: RegistryConfig = {
+  maxComponents: 1000,
+  cleanupInterval: 60000, // 1 minute
+  useLRU: true,
+  enableNamespaces: true
+};
+
+/**
+ * Platform-agnostic component registry.
+ * Manages compiled React components with namespace isolation and lifecycle management.
+ */
+export class ComponentRegistry {
+  private registry: Map<string, RegistryEntry>;
+  private config: RegistryConfig;
+  private cleanupTimer?: NodeJS.Timeout | number;
+  
+  /**
+   * Creates a new ComponentRegistry instance
+   * @param config - Optional registry configuration
+   */
+  constructor(config?: Partial<RegistryConfig>) {
+    this.config = { ...DEFAULT_REGISTRY_CONFIG, ...config };
+    this.registry = new Map();
+    
+    // Start cleanup timer if configured
+    if (this.config.cleanupInterval > 0) {
+      this.startCleanupTimer();
+    }
+  }
+
+  /**
+   * Registers a compiled component
+   * @param name - Component name
+   * @param component - Compiled component
+   * @param namespace - Component namespace (default: 'Global')
+   * @param version - Component version (default: 'v1')
+   * @param tags - Optional tags for categorization
+   * @returns The registered component's metadata
+   */
+  register(
+    name: string,
+    component: any,
+    namespace: string = 'Global',
+    version: string = 'v1',
+    tags?: string[]
+  ): ComponentMetadata {
+    const id = this.generateRegistryKey(name, namespace, version);
+    
+    // Create metadata
+    const metadata: ComponentMetadata = {
+      id,
+      name,
+      version,
+      namespace,
+      registeredAt: new Date(),
+      tags
+    };
+
+    // Create registry entry
+    const entry: RegistryEntry = {
+      component,
+      metadata,
+      lastAccessed: new Date(),
+      refCount: 0
+    };
+
+    // Check capacity
+    if (this.registry.size >= this.config.maxComponents && this.config.useLRU) {
+      this.evictLRU();
+    }
+
+    // Store in registry
+    this.registry.set(id, entry);
+
+    return metadata;
+  }
+
+  /**
+   * Gets a component from the registry
+   * @param name - Component name
+   * @param namespace - Component namespace
+   * @param version - Component version
+   * @returns The component if found, undefined otherwise
+   */
+  get(name: string, namespace: string = 'Global', version?: string): any {
+    const id = version 
+      ? this.generateRegistryKey(name, namespace, version)
+      : this.findLatestVersion(name, namespace);
+
+    if (!id) return undefined;
+
+    const entry = this.registry.get(id);
+    if (entry) {
+      // Update access time and increment ref count
+      entry.lastAccessed = new Date();
+      entry.refCount++;
+      return entry.component;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Checks if a component exists in the registry
+   * @param name - Component name
+   * @param namespace - Component namespace
+   * @param version - Component version
+   * @returns true if the component exists
+   */
+  has(name: string, namespace: string = 'Global', version?: string): boolean {
+    const id = version 
+      ? this.generateRegistryKey(name, namespace, version)
+      : this.findLatestVersion(name, namespace);
+
+    return id ? this.registry.has(id) : false;
+  }
+
+  /**
+   * Removes a component from the registry
+   * @param name - Component name
+   * @param namespace - Component namespace
+   * @param version - Component version
+   * @returns true if the component was removed
+   */
+  unregister(name: string, namespace: string = 'Global', version?: string): boolean {
+    const id = version 
+      ? this.generateRegistryKey(name, namespace, version)
+      : this.findLatestVersion(name, namespace);
+
+    if (!id) return false;
+
+    return this.registry.delete(id);
+  }
+
+  /**
+   * Gets all components in a namespace
+   * @param namespace - Namespace to query
+   * @returns Array of components in the namespace
+   */
+  getNamespace(namespace: string): ComponentMetadata[] {
+    const components: ComponentMetadata[] = [];
+    
+    for (const entry of this.registry.values()) {
+      if (entry.metadata.namespace === namespace) {
+        components.push(entry.metadata);
+      }
+    }
+
+    return components;
+  }
+
+  /**
+   * Gets all registered namespaces
+   * @returns Array of unique namespace names
+   */
+  getNamespaces(): string[] {
+    const namespaces = new Set<string>();
+    
+    for (const entry of this.registry.values()) {
+      namespaces.add(entry.metadata.namespace);
+    }
+
+    return Array.from(namespaces);
+  }
+
+  /**
+   * Gets components by tags
+   * @param tags - Tags to search for
+   * @returns Array of components matching any of the tags
+   */
+  getByTags(tags: string[]): ComponentMetadata[] {
+    const components: ComponentMetadata[] = [];
+    
+    for (const entry of this.registry.values()) {
+      if (entry.metadata.tags?.some(tag => tags.includes(tag))) {
+        components.push(entry.metadata);
+      }
+    }
+
+    return components;
+  }
+
+  /**
+   * Decrements reference count for a component
+   * @param name - Component name
+   * @param namespace - Component namespace
+   * @param version - Component version
+   */
+  release(name: string, namespace: string = 'Global', version?: string): void {
+    const id = version 
+      ? this.generateRegistryKey(name, namespace, version)
+      : this.findLatestVersion(name, namespace);
+
+    if (!id) return;
+
+    const entry = this.registry.get(id);
+    if (entry && entry.refCount > 0) {
+      entry.refCount--;
+    }
+  }
+
+  /**
+   * Clears all components from the registry
+   */
+  clear(): void {
+    this.registry.clear();
+  }
+
+  /**
+   * Gets the current size of the registry
+   * @returns Number of registered components
+   */
+  size(): number {
+    return this.registry.size;
+  }
+
+  /**
+   * Performs cleanup of unused components
+   * @param force - Force cleanup regardless of reference count
+   * @returns Number of components removed
+   */
+  cleanup(force: boolean = false): number {
+    const toRemove: string[] = [];
+    const now = Date.now();
+
+    for (const [id, entry] of this.registry) {
+      // Remove if no references and hasn't been accessed recently
+      const timeSinceAccess = now - entry.lastAccessed.getTime();
+      const isUnused = entry.refCount === 0 && timeSinceAccess > this.config.cleanupInterval;
+
+      if (force || isUnused) {
+        toRemove.push(id);
+      }
+    }
+
+    for (const id of toRemove) {
+      this.registry.delete(id);
+    }
+
+    return toRemove.length;
+  }
+
+  /**
+   * Gets registry statistics
+   * @returns Object containing registry stats
+   */
+  getStats(): {
+    totalComponents: number;
+    namespaces: number;
+    totalRefCount: number;
+    oldestComponent?: Date;
+    newestComponent?: Date;
+  } {
+    let totalRefCount = 0;
+    let oldest: Date | undefined;
+    let newest: Date | undefined;
+
+    for (const entry of this.registry.values()) {
+      totalRefCount += entry.refCount;
+      
+      if (!oldest || entry.metadata.registeredAt < oldest) {
+        oldest = entry.metadata.registeredAt;
+      }
+      
+      if (!newest || entry.metadata.registeredAt > newest) {
+        newest = entry.metadata.registeredAt;
+      }
+    }
+
+    return {
+      totalComponents: this.registry.size,
+      namespaces: this.getNamespaces().length,
+      totalRefCount,
+      oldestComponent: oldest,
+      newestComponent: newest
+    };
+  }
+
+  /**
+   * Destroys the registry and cleans up resources
+   */
+  destroy(): void {
+    this.stopCleanupTimer();
+    this.clear();
+  }
+
+  /**
+   * Generates a unique registry key
+   * @param name - Component name
+   * @param namespace - Component namespace
+   * @param version - Component version
+   * @returns Registry key
+   */
+  private generateRegistryKey(name: string, namespace: string, version: string): string {
+    if (this.config.enableNamespaces) {
+      return `${namespace}::${name}@${version}`;
+    }
+    return `${name}@${version}`;
+  }
+
+  /**
+   * Finds the latest version of a component
+   * @param name - Component name
+   * @param namespace - Component namespace
+   * @returns Registry key of latest version or undefined
+   */
+  private findLatestVersion(name: string, namespace: string): string | undefined {
+    let latestKey: string | undefined;
+    let latestDate: Date | undefined;
+
+    for (const [key, entry] of this.registry) {
+      if (entry.metadata.name === name && 
+          entry.metadata.namespace === namespace) {
+        if (!latestDate || entry.metadata.registeredAt > latestDate) {
+          latestDate = entry.metadata.registeredAt;
+          latestKey = key;
+        }
+      }
+    }
+
+    return latestKey;
+  }
+
+  /**
+   * Evicts the least recently used component
+   */
+  private evictLRU(): void {
+    let lruKey: string | undefined;
+    let lruTime: Date | undefined;
+
+    for (const [key, entry] of this.registry) {
+      // Skip components with active references
+      if (entry.refCount > 0) continue;
+
+      if (!lruTime || entry.lastAccessed < lruTime) {
+        lruTime = entry.lastAccessed;
+        lruKey = key;
+      }
+    }
+
+    if (lruKey) {
+      this.registry.delete(lruKey);
+    }
+  }
+
+  /**
+   * Starts the automatic cleanup timer
+   */
+  private startCleanupTimer(): void {
+    this.cleanupTimer = setInterval(() => {
+      this.cleanup();
+    }, this.config.cleanupInterval);
+  }
+
+  /**
+   * Stops the automatic cleanup timer
+   */
+  private stopCleanupTimer(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer as any);
+      this.cleanupTimer = undefined;
+    }
+  }
+}

package/src/registry/component-resolver.ts

@@ -0,0 +1,275 @@
+/**
+ * @fileoverview Component dependency resolver for managing component relationships.
+ * Handles resolution of child components and dependency graphs.
+ * @module @memberjunction/react-runtime/registry
+ */
+
+import { ComponentRegistry } from './component-registry';
+
+/**
+ * Component specification interface matching Skip component structure
+ */
+export interface ComponentSpec {
+  componentName: string;
+  componentCode?: string;
+  childComponents?: ComponentSpec[];
+  components?: ComponentSpec[]; // Alternative property name for children
+}
+
+/**
+ * Resolved component map for passing to React components
+ */
+export interface ResolvedComponents {
+  [componentName: string]: any;
+}
+
+/**
+ * Component dependency resolver.
+ * Resolves component hierarchies and manages dependencies between components.
+ */
+export class ComponentResolver {
+  private registry: ComponentRegistry;
+
+  /**
+   * Creates a new ComponentResolver instance
+   * @param registry - Component registry to use for resolution
+   */
+  constructor(registry: ComponentRegistry) {
+    this.registry = registry;
+  }
+
+  /**
+   * Resolves all components for a given component specification
+   * @param spec - Root component specification
+   * @param namespace - Namespace for component resolution
+   * @returns Map of component names to resolved components
+   */
+  resolveComponents(spec: ComponentSpec, namespace: string = 'Global'): ResolvedComponents {
+    const resolved: ResolvedComponents = {};
+    
+    // Resolve the component hierarchy
+    this.resolveComponentHierarchy(spec, resolved, namespace);
+    
+    return resolved;
+  }
+
+  /**
+   * Recursively resolves a component hierarchy
+   * @param spec - Component specification
+   * @param resolved - Map to store resolved components
+   * @param namespace - Namespace for resolution
+   * @param visited - Set of visited component names to prevent cycles
+   */
+  private resolveComponentHierarchy(
+    spec: ComponentSpec,
+    resolved: ResolvedComponents,
+    namespace: string,
+    visited: Set<string> = new Set()
+  ): void {
+    // Prevent circular dependencies
+    if (visited.has(spec.componentName)) {
+      console.warn(`Circular dependency detected for component: ${spec.componentName}`);
+      return;
+    }
+    visited.add(spec.componentName);
+
+    // Try to get component from registry
+    const component = this.registry.get(spec.componentName, namespace);
+    if (component) {
+      resolved[spec.componentName] = component;
+    }
+
+    // Process child components (handle both property names)
+    const children = spec.childComponents || spec.components || [];
+    for (const child of children) {
+      this.resolveComponentHierarchy(child, resolved, namespace, visited);
+    }
+  }
+
+  /**
+   * Validates that all required components are available
+   * @param spec - Component specification to validate
+   * @param namespace - Namespace for validation
+   * @returns Array of missing component names
+   */
+  validateDependencies(spec: ComponentSpec, namespace: string = 'Global'): string[] {
+    const missing: string[] = [];
+    const checked = new Set<string>();
+    
+    this.checkDependencies(spec, namespace, missing, checked);
+    
+    return missing;
+  }
+
+  /**
+   * Recursively checks for missing dependencies
+   * @param spec - Component specification
+   * @param namespace - Namespace for checking
+   * @param missing - Array to collect missing components
+   * @param checked - Set of already checked components
+   */
+  private checkDependencies(
+    spec: ComponentSpec,
+    namespace: string,
+    missing: string[],
+    checked: Set<string>
+  ): void {
+    if (checked.has(spec.componentName)) return;
+    checked.add(spec.componentName);
+
+    // Check if component exists in registry
+    if (!this.registry.has(spec.componentName, namespace)) {
+      missing.push(spec.componentName);
+    }
+
+    // Check children
+    const children = spec.childComponents || spec.components || [];
+    for (const child of children) {
+      this.checkDependencies(child, namespace, missing, checked);
+    }
+  }
+
+  /**
+   * Gets the dependency graph for a component specification
+   * @param spec - Component specification
+   * @returns Dependency graph as adjacency list
+   */
+  getDependencyGraph(spec: ComponentSpec): Map<string, string[]> {
+    const graph = new Map<string, string[]>();
+    const visited = new Set<string>();
+    
+    this.buildDependencyGraph(spec, graph, visited);
+    
+    return graph;
+  }
+
+  /**
+   * Recursively builds the dependency graph
+   * @param spec - Component specification
+   * @param graph - Graph to build
+   * @param visited - Set of visited components
+   */
+  private buildDependencyGraph(
+    spec: ComponentSpec,
+    graph: Map<string, string[]>,
+    visited: Set<string>
+  ): void {
+    if (visited.has(spec.componentName)) return;
+    visited.add(spec.componentName);
+
+    const children = spec.childComponents || spec.components || [];
+    const dependencies = children.map(child => child.componentName);
+    
+    graph.set(spec.componentName, dependencies);
+
+    // Recursively process children
+    for (const child of children) {
+      this.buildDependencyGraph(child, graph, visited);
+    }
+  }
+
+  /**
+   * Performs topological sort on component dependencies
+   * @param spec - Root component specification
+   * @returns Array of component names in dependency order
+   */
+  getLoadOrder(spec: ComponentSpec): string[] {
+    const graph = this.getDependencyGraph(spec);
+    const visited = new Set<string>();
+    const stack: string[] = [];
+
+    // Perform DFS on all nodes
+    for (const node of graph.keys()) {
+      if (!visited.has(node)) {
+        this.topologicalSortDFS(node, graph, visited, stack);
+      }
+    }
+
+    // Reverse to get correct load order
+    return stack.reverse();
+  }
+
+  /**
+   * DFS helper for topological sort
+   * @param node - Current node
+   * @param graph - Dependency graph
+   * @param visited - Set of visited nodes
+   * @param stack - Result stack
+   */
+  private topologicalSortDFS(
+    node: string,
+    graph: Map<string, string[]>,
+    visited: Set<string>,
+    stack: string[]
+  ): void {
+    visited.add(node);
+
+    const dependencies = graph.get(node) || [];
+    for (const dep of dependencies) {
+      if (!visited.has(dep)) {
+        this.topologicalSortDFS(dep, graph, visited, stack);
+      }
+    }
+
+    stack.push(node);
+  }
+
+  /**
+   * Resolves components in the correct dependency order
+   * @param spec - Root component specification
+   * @param namespace - Namespace for resolution
+   * @returns Ordered array of resolved components
+   */
+  resolveInOrder(spec: ComponentSpec, namespace: string = 'Global'): Array<{
+    name: string;
+    component: any;
+  }> {
+    const loadOrder = this.getLoadOrder(spec);
+    const resolved: Array<{ name: string; component: any }> = [];
+
+    for (const name of loadOrder) {
+      const component = this.registry.get(name, namespace);
+      if (component) {
+        resolved.push({ name, component });
+      }
+    }
+
+    return resolved;
+  }
+
+  /**
+   * Creates a flattened list of all component specifications
+   * @param spec - Root component specification
+   * @returns Array of all component specs in the hierarchy
+   */
+  flattenComponentSpecs(spec: ComponentSpec): ComponentSpec[] {
+    const flattened: ComponentSpec[] = [];
+    const visited = new Set<string>();
+
+    this.collectComponentSpecs(spec, flattened, visited);
+
+    return flattened;
+  }
+
+  /**
+   * Recursively collects component specifications
+   * @param spec - Current component specification
+   * @param collected - Array to collect specs
+   * @param visited - Set of visited component names
+   */
+  private collectComponentSpecs(
+    spec: ComponentSpec,
+    collected: ComponentSpec[],
+    visited: Set<string>
+  ): void {
+    if (visited.has(spec.componentName)) return;
+    visited.add(spec.componentName);
+
+    collected.push(spec);
+
+    const children = spec.childComponents || spec.components || [];
+    for (const child of children) {
+      this.collectComponentSpecs(child, collected, visited);
+    }
+  }
+}

package/src/registry/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Registry module exports
+ * @module @memberjunction/react-runtime/registry
+ */
+
+export { ComponentRegistry } from './component-registry';
+export { ComponentResolver, ComponentSpec, ResolvedComponents } from './component-resolver';