@memberjunction/core 2.128.0 → 2.129.0

package/dist/generic/baseEngineRegistry.d.ts

@@ -0,0 +1,247 @@
+import { BaseSingleton } from '@memberjunction/global';
+/**
+ * Information about a registered engine instance
+ */
+export interface EngineRegistrationInfo {
+    /**
+     * The constructor/class name of the engine
+     */
+    className: string;
+    /**
+     * Reference to the engine instance
+     */
+    instance: unknown;
+    /**
+     * When the engine was registered
+     */
+    registeredAt: Date;
+    /**
+     * When the engine was last loaded/configured
+     */
+    lastLoadedAt: Date | null;
+    /**
+     * Whether the engine is currently loaded
+     */
+    isLoaded: boolean;
+    /**
+     * Estimated memory usage in bytes (if calculable)
+     */
+    estimatedMemoryBytes: number;
+    /**
+     * Number of data items loaded in the engine
+     */
+    itemCount: number;
+}
+/**
+ * Memory statistics for all registered engines
+ */
+export interface EngineMemoryStats {
+    /**
+     * Total number of registered engines
+     */
+    totalEngines: number;
+    /**
+     * Number of engines that are currently loaded
+     */
+    loadedEngines: number;
+    /**
+     * Total estimated memory across all engines
+     */
+    totalEstimatedMemoryBytes: number;
+    /**
+     * Per-engine breakdown
+     */
+    engineStats: EngineRegistrationInfo[];
+}
+/**
+ * BaseEngineRegistry is a central registry for tracking all BaseEngine instances.
+ *
+ * It provides:
+ * - Registration and tracking of engine singletons
+ * - Memory usage estimation across all engines
+ * - Cross-engine data sharing coordination
+ * - Bulk operations (refresh all, invalidate all)
+ *
+ * @example
+ * ```typescript
+ * // Register an engine (typically done automatically by BaseEngine)
+ * BaseEngineRegistry.Instance.RegisterEngine(MyEngine.Instance);
+ *
+ * // Get memory stats
+ * const stats = BaseEngineRegistry.Instance.GetMemoryStats();
+ * console.log(`Total engines: ${stats.totalEngines}`);
+ * console.log(`Total memory: ${(stats.totalEstimatedMemoryBytes / 1024 / 1024).toFixed(2)} MB`);
+ * ```
+ */
+export declare class BaseEngineRegistry extends BaseSingleton<BaseEngineRegistry> {
+    private _engines;
+    /**
+     * Cache of estimated bytes per row for each entity type.
+     * This avoids re-sampling the same entity type multiple times during a session.
+     */
+    private _entitySizeCache;
+    /**
+     * Tracks which engines have loaded which entities.
+     * Key: entity name, Value: Set of engine class names
+     */
+    private _entityLoadTracking;
+    /**
+     * Tracks which engine instances have already recorded their entity loads.
+     * Uses WeakSet so engine instances can be garbage collected when no longer in use.
+     * This prevents false positive warnings when a subclass and base class share the same singleton.
+     */
+    private _recordedEngineInstances;
+    /**
+     * Returns the singleton instance of BaseEngineRegistry
+     */
+    static get Instance(): BaseEngineRegistry;
+    protected constructor();
+    /**
+     * Returns the entity load tracking data as a Map suitable for TelemetryAnalyzerContext.
+     * Key: entity name, Value: array of engine class names that have loaded this entity.
+     */
+    GetEntityLoadTrackingMap(): Map<string, string[]>;
+    /**
+     * Register an engine instance with the registry.
+     * This is typically called automatically by BaseEngine during Config().
+     *
+     * @param engine - The engine instance to register
+     * @param className - Optional class name override (uses constructor name by default)
+     */
+    RegisterEngine(engine: unknown, className?: string): void;
+    /**
+     * Unregister an engine from the registry
+     *
+     * @param engine - The engine instance to unregister
+     */
+    UnregisterEngine(engine: unknown): void;
+    /**
+     * Get a registered engine by class name
+     *
+     * @param className - The class name of the engine
+     * @returns The engine instance or null if not found
+     */
+    GetEngine<T>(className: string): T | null;
+    /**
+     * Get all registered engines
+     *
+     * @returns Array of all registered engine instances
+     */
+    GetAllEngines(): unknown[];
+    /**
+     * Get registration info for a specific engine
+     *
+     * @param className - The class name of the engine
+     * @returns The registration info or null if not found
+     */
+    GetEngineInfo(className: string): EngineRegistrationInfo | null;
+    /**
+     * Get memory statistics for all registered engines
+     *
+     * @returns Memory statistics object
+     */
+    GetMemoryStats(): EngineMemoryStats;
+    /**
+     * Refresh all loaded engines
+     *
+     * @returns Number of engines refreshed
+     */
+    RefreshAllEngines(): Promise<number>;
+    /**
+     * Notify the registry that an engine has been loaded/configured
+     *
+     * @param engine - The engine that was loaded
+     */
+    NotifyEngineLoaded(engine: unknown): void;
+    /**
+     * Get a list of all engine class names
+     */
+    GetEngineNames(): string[];
+    /**
+     * Check if an engine is registered
+     */
+    IsRegistered(className: string): boolean;
+    /**
+     * Clear all registrations (use with caution, primarily for testing)
+     */
+    Reset(): void;
+    /**
+     * Check if an engine is loaded by looking for a 'Loaded' property
+     */
+    private CheckEngineLoaded;
+    /**
+     * Check if an engine has a RefreshAllItems method
+     */
+    private HasRefreshMethod;
+    /**
+     * Estimate memory usage of an engine by examining its data properties
+     */
+    private EstimateEngineMemory;
+    /**
+     * Count the number of data items in an engine
+     */
+    private CountEngineItems;
+    /**
+     * Default bytes per row when we can't sample (fallback)
+     */
+    private static readonly DEFAULT_BYTES_PER_ROW;
+    /**
+     * Estimate the size of an array in bytes by sampling the first row.
+     * Uses a cache to avoid re-sampling the same entity type multiple times.
+     */
+    private EstimateArraySize;
+    /**
+     * Get the estimated bytes per row for an item, using cache when possible.
+     */
+    private GetBytesPerRow;
+    /**
+     * Sample a single item to estimate its size in bytes.
+     * For BaseEntity objects, uses GetAll() to get plain field values.
+     */
+    private SampleItemSize;
+    /**
+     * Estimate the size of a single value in bytes.
+     */
+    private EstimateValueSize;
+    /**
+     * Clear the entity size cache (useful if schema changes)
+     */
+    ClearSizeCache(): void;
+    /**
+     * Records that an engine has loaded a specific entity.
+     * If another engine has already loaded this entity, a warning is queued.
+     *
+     * @param engineClassName - The class name of the engine loading the entity
+     * @param entityName - The name of the entity being loaded
+     */
+    RecordEntityLoad(engineClassName: string, entityName: string): void;
+    /**
+     * Records that an engine has loaded multiple entities.
+     * Convenience method for batch recording.
+     * Uses instance identity to prevent false positives when a subclass and base class
+     * share the same singleton (e.g., AIEngine extends AIEngineBase).
+     *
+     * @param engine - The engine instance that loaded the entities
+     * @param entityNames - Array of entity names being loaded
+     */
+    RecordEntityLoads(engine: object, entityNames: string[]): void;
+    /**
+     * Gets a list of engines that have loaded a specific entity.
+     *
+     * @param entityName - The name of the entity
+     * @returns Array of engine class names that have loaded this entity
+     */
+    GetEnginesLoadingEntity(entityName: string): string[];
+    /**
+     * Gets all entities that have been loaded by multiple engines.
+     *
+     * @returns Map of entity name to array of engine class names
+     */
+    GetRedundantlyLoadedEntities(): Map<string, string[]>;
+    /**
+     * Clears entity load tracking data.
+     * Useful for testing or when engines are being reconfigured.
+     */
+    ClearEntityLoadTracking(): void;
+}
+//# sourceMappingURL=baseEngineRegistry.d.ts.map

package/dist/generic/baseEngineRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseEngineRegistry.d.ts","sourceRoot":"","sources":["../../src/generic/baseEngineRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAwC,MAAM,wBAAwB,CAAC;AAI7F;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACnC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB;;OAEG;IACH,YAAY,EAAE,IAAI,CAAC;IACnB;;OAEG;IACH,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB;;OAEG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,yBAAyB,EAAE,MAAM,CAAC;IAClC;;OAEG;IACH,WAAW,EAAE,sBAAsB,EAAE,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,kBAAmB,SAAQ,aAAa,CAAC,kBAAkB,CAAC;IACrE,OAAO,CAAC,QAAQ,CAAkD;IAElE;;;OAGG;IACH,OAAO,CAAC,gBAAgB,CAAkC;IAE1D;;;OAGG;IACH,OAAO,CAAC,mBAAmB,CAAuC;IAElE;;;;OAIG;IACH,OAAO,CAAC,wBAAwB,CAAkC;IAElE;;OAEG;IACH,WAAkB,QAAQ,IAAI,kBAAkB,CAE/C;IAED,SAAS;IAYT;;;OAGG;IACI,wBAAwB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAQxD;;;;;;OAMG;IACI,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAyBhE;;;;OAIG;IACI,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAK9C;;;;;OAKG;IACI,SAAS,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAKhD;;;;OAIG;IACI,aAAa,IAAI,OAAO,EAAE;IAIjC;;;;;OAKG;IACI,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,sBAAsB,GAAG,IAAI;IAItE;;;;OAIG;IACI,cAAc,IAAI,iBAAiB;IAkB1C;;;;OAIG;IACU,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAoBjD;;;;OAIG;IACI,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAchD;;OAEG;IACI,cAAc,IAAI,MAAM,EAAE;IAIjC;;OAEG;IACI,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAI/C;;OAEG;IACI,KAAK,IAAI,IAAI;IAIpB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAOxB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAmC5B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAqBxB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAO;IAEpD;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;OAEG;IACH,OAAO,CAAC,cAAc;IA2BtB;;;OAGG;IACH,OAAO,CAAC,cAAc;IA8BtB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAuBzB;;OAEG;IACI,cAAc,IAAI,IAAI;IAQ7B;;;;;;OAMG;IACI,gBAAgB,CAAC,eAAe,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAiB1E;;;;;;;;OAQG;IACI,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,IAAI;IAerE;;;;;OAKG;IACI,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAK5D;;;;OAIG;IACI,4BAA4B,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAU5D;;;OAGG;IACI,uBAAuB,IAAI,IAAI;CAGzC"}