@memberjunction/core 2.127.0 → 2.129.0

package/dist/generic/providerBase.js

@@ -5,9 +5,11 @@ exports.ProviderBase = exports.AllMetadataArrays = exports.MetadataFromSimpleObj
 const baseEntity_1 = require("./baseEntity");
 const entityInfo_1 = require("./entityInfo");
 const interfaces_1 = require("./interfaces");
+const localCacheManager_1 = require("./localCacheManager");
 const applicationInfo_1 = require("../generic/applicationInfo");
 const securityInfo_1 = require("./securityInfo");
 const global_1 = require("@memberjunction/global");
+const telemetryManager_1 = require("./telemetryManager");
 const logging_1 = require("./logging");
 const queryInfo_1 = require("./queryInfo");
 const libraryInfo_1 = require("./libraryInfo");
@@ -98,6 +100,127 @@ class ProviderBase {
         this._refresh = false;
         this._cachedVisibleExplorerNavigationItems = null;
     }
+    // ========================================================================
+    // PUBLIC API METHODS - Orchestrate Pre → Cache → Internal → Post flow
+    // ========================================================================
+    /**
+     * Runs a view based on the provided parameters.
+     * This method orchestrates the full execution flow: pre-processing, cache check,
+     * internal execution, post-processing, and cache storage.
+     * @param params - The view parameters
+     * @param contextUser - Optional user context for permissions (required server-side)
+     * @returns The view results
+     */
+    async RunView(params, contextUser) {
+        // Pre-processing: telemetry, validation, entity status check
+        const preResult = await this.PreRunView(params, contextUser);
+        // Check for cached result - end telemetry with cache hit info
+        if (preResult.cachedResult) {
+            telemetryManager_1.TelemetryManager.Instance.EndEvent(preResult.telemetryEventId, {
+                cacheHit: true,
+                cacheStatus: preResult.cacheStatus,
+                resultCount: preResult.cachedResult.Results?.length ?? 0
+            });
+            return preResult.cachedResult;
+        }
+        // Execute the internal implementation
+        const result = await this.InternalRunView(params, contextUser);
+        // Post-processing: transformation, cache storage, telemetry end
+        await this.PostRunView(result, params, preResult, contextUser);
+        return result;
+    }
+    /**
+     * Runs multiple views based on the provided parameters.
+     * This method orchestrates the full execution flow for batch operations.
+     * @param params - Array of view parameters
+     * @param contextUser - Optional user context for permissions (required server-side)
+     * @returns Array of view results
+     */
+    async RunViews(params, contextUser) {
+        // Pre-processing for batch
+        const preResult = await this.PreRunViews(params, contextUser);
+        // Check for smart cache check mode
+        if (preResult.useSmartCacheCheck && preResult.smartCacheCheckParams) {
+            return this.executeSmartCacheCheck(params, preResult, contextUser);
+        }
+        // Check for cached results - if all are cached, end telemetry and return early
+        if (preResult.allCached && preResult.cachedResults) {
+            const totalResults = preResult.cachedResults.reduce((sum, r) => sum + (r.Results?.length ?? 0), 0);
+            telemetryManager_1.TelemetryManager.Instance.EndEvent(preResult.telemetryEventId, {
+                cacheHit: true,
+                allCached: true,
+                batchSize: params.length,
+                totalResultCount: totalResults
+            });
+            return preResult.cachedResults;
+        }
+        // Execute the internal implementation for non-cached items
+        const results = await this.InternalRunViews(preResult.uncachedParams || params, contextUser);
+        // Merge cached and fresh results if needed
+        const finalResults = preResult.cachedResults
+            ? this.mergeCachedAndFreshResults(preResult, results)
+            : results;
+        // Post-processing for batch
+        await this.PostRunViews(finalResults, params, preResult, contextUser);
+        return finalResults;
+    }
+    /**
+     * Runs a query based on the provided parameters.
+     * This method orchestrates the full execution flow: pre-processing, cache check,
+     * internal execution, post-processing, and cache storage.
+     * @param params - The query parameters
+     * @param contextUser - Optional user context for permissions (required server-side)
+     * @returns The query results
+     */
+    async RunQuery(params, contextUser) {
+        // Pre-processing: telemetry, cache check
+        const preResult = await this.PreRunQuery(params, contextUser);
+        // Check for cached result - end telemetry with cache hit info
+        if (preResult.cachedResult) {
+            telemetryManager_1.TelemetryManager.Instance.EndEvent(preResult.telemetryEventId, {
+                cacheHit: true,
+                cacheStatus: preResult.cacheStatus,
+                resultCount: preResult.cachedResult.Results?.length ?? 0
+            });
+            return preResult.cachedResult;
+        }
+        // Execute the internal implementation
+        const result = await this.InternalRunQuery(params, contextUser);
+        // Post-processing: cache storage, telemetry end
+        await this.PostRunQuery(result, params, preResult, contextUser);
+        return result;
+    }
+    /**
+     * Runs multiple queries based on the provided parameters.
+     * This method orchestrates the full execution flow for batch query operations.
+     * @param params - Array of query parameters
+     * @param contextUser - Optional user context for permissions (required server-side)
+     * @returns Array of query results
+     */
+    async RunQueries(params, contextUser) {
+        // Pre-processing for batch
+        const preResult = await this.PreRunQueries(params, contextUser);
+        // Check for cached results - if all are cached, end telemetry and return early
+        if (preResult.allCached && preResult.cachedResults) {
+            const totalResults = preResult.cachedResults.reduce((sum, r) => sum + (r.Results?.length ?? 0), 0);
+            telemetryManager_1.TelemetryManager.Instance.EndEvent(preResult.telemetryEventId, {
+                cacheHit: true,
+                allCached: true,
+                batchSize: params.length,
+                totalResultCount: totalResults
+            });
+            return preResult.cachedResults;
+        }
+        // Execute the internal implementation for non-cached items
+        const results = await this.InternalRunQueries(preResult.uncachedParams || params, contextUser);
+        // Merge cached and fresh results if needed
+        const finalResults = preResult.cachedResults
+            ? this.mergeQueryCachedAndFreshResults(preResult, results)
+            : results;
+        // Post-processing for batch
+        await this.PostRunQueries(finalResults, params, preResult, contextUser);
+        return finalResults;
+    }
     /**
      * Used to check to see if the entity in question is active or not
      * If it is not active, it will throw an exception or log a warning depending on the status of the entity being
@@ -113,12 +236,609 @@ class ProviderBase {
         }
         entityInfo_1.EntityInfo.AssertEntityActiveStatus(entity, callerName);
     }
+    // Type aliases for cleaner code
+    get PreRunViewResult() { return this._preRunViewResultType; }
+    get PreRunViewsResult() { return this._preRunViewsResultType; }
+    get PreRunQueryResult() { return this._preRunQueryResultType; }
+    get PreRunQueriesResult() { return this._preRunQueriesResultType; }
+    // ========================================================================
+    // PRE-PROCESSING HOOKS
+    // ========================================================================
     /**
-     * Base class pre-processor that all sub-classes should call before they start their RunView process
-     * @param params
-     * @param contextUser
+     * Pre-processing hook for RunView.
+     * Handles telemetry, validation, entity status check, and cache lookup.
+     * @param params - The view parameters
+     * @param contextUser - Optional user context
+     * @returns Pre-processing result with cache status and optional cached result
+     */
+    async PreRunView(params, contextUser) {
+        const preViewStart = performance.now();
+        // Start telemetry tracking
+        const telemetryStart = performance.now();
+        const telemetryEventId = telemetryManager_1.TelemetryManager.Instance.StartEvent('RunView', 'ProviderBase.RunView', {
+            EntityName: params.EntityName,
+            ViewID: params.ViewID,
+            ViewName: params.ViewName,
+            ExtraFilter: params.ExtraFilter,
+            OrderBy: params.OrderBy,
+            ResultType: params.ResultType,
+            MaxRows: params.MaxRows,
+            StartRow: params.StartRow,
+            CacheLocal: params.CacheLocal,
+            _fromEngine: params._fromEngine
+        }, contextUser?.ID);
+        const telemetryTime = performance.now() - telemetryStart;
+        // Entity status check
+        const entityCheckStart = performance.now();
+        await this.EntityStatusCheck(params, 'PreRunView');
+        const entityCheckTime = performance.now() - entityCheckStart;
+        // Handle entity_object result type - need all fields
+        const entityLookupStart = performance.now();
+        if (params.ResultType === 'entity_object') {
+            const entity = this.Entities.find(e => e.Name.trim().toLowerCase() === params.EntityName.trim().toLowerCase());
+            if (!entity)
+                throw new Error(`Entity ${params.EntityName} not found in metadata`);
+            params.Fields = entity.Fields.map(f => f.Name);
+        }
+        const entityLookupTime = performance.now() - entityLookupStart;
+        // Check local cache if enabled
+        const cacheCheckStart = performance.now();
+        let cacheStatus = 'disabled';
+        let cachedResult;
+        let fingerprint;
+        if (params.CacheLocal && localCacheManager_1.LocalCacheManager.Instance.IsInitialized) {
+            fingerprint = localCacheManager_1.LocalCacheManager.Instance.GenerateRunViewFingerprint(params, this.InstanceConnectionString);
+            const cached = await localCacheManager_1.LocalCacheManager.Instance.GetRunViewResult(fingerprint);
+            if (cached) {
+                // Reconstruct RunViewResult from cached data
+                cachedResult = {
+                    Success: true,
+                    Results: cached.results,
+                    RowCount: cached.results.length,
+                    TotalRowCount: cached.results.length,
+                    ExecutionTime: 0, // Cached, no execution time
+                    ErrorMessage: '',
+                    UserViewRunID: ''
+                };
+                cacheStatus = 'hit';
+            }
+            else {
+                cacheStatus = 'miss';
+            }
+        }
+        const cacheCheckTime = performance.now() - cacheCheckStart;
+        const totalPreTime = performance.now() - preViewStart;
+        if (totalPreTime > 50) {
+            console.log(`[PERF-PRE] PreRunView ${params.EntityName}: ${totalPreTime.toFixed(1)}ms (telemetry=${telemetryTime.toFixed(1)}ms, entityCheck=${entityCheckTime.toFixed(1)}ms, entityLookup=${entityLookupTime.toFixed(1)}ms, cache=${cacheCheckTime.toFixed(1)}ms)`);
+        }
+        return {
+            telemetryEventId,
+            cacheStatus,
+            cachedResult,
+            fingerprint
+        };
+    }
+    /**
+     * Pre-processing hook for RunViews (batch).
+     * Handles telemetry, validation, and cache lookup for multiple views.
+     * @param params - Array of view parameters
+     * @param contextUser - Optional user context
+     * @returns Pre-processing result with cache status for each view
+     */
+    async PreRunViews(params, contextUser) {
+        // Start telemetry tracking for batch operation
+        const fromEngine = params.some(p => p._fromEngine);
+        const telemetryEventId = telemetryManager_1.TelemetryManager.Instance.StartEvent('RunView', 'ProviderBase.RunViews', {
+            BatchSize: params.length,
+            Entities: params.map(p => p.EntityName || p.ViewName || p.ViewID).filter(Boolean),
+            _fromEngine: fromEngine
+        }, contextUser?.ID);
+        // Check if any params have CacheLocal enabled - smart caching is always used when caching locally
+        const useSmartCacheCheck = params.some(p => p.CacheLocal);
+        // If local caching is enabled, use smart cache check flow
+        if (useSmartCacheCheck && localCacheManager_1.LocalCacheManager.Instance.IsInitialized) {
+            return this.prepareSmartCacheCheckParams(params, telemetryEventId, contextUser);
+        }
+        // Traditional caching flow
+        const cacheStatusMap = new Map();
+        const uncachedParams = [];
+        const cachedResults = [];
+        let allCached = true;
+        for (let i = 0; i < params.length; i++) {
+            const param = params[i];
+            // Entity status check
+            await this.EntityStatusCheck(param, 'PreRunViews');
+            // Handle entity_object result type - need all fields
+            if (param.ResultType === 'entity_object') {
+                const entity = this.Entities.find(e => e.Name.trim().toLowerCase() === param.EntityName.trim().toLowerCase());
+                if (!entity) {
+                    throw new Error(`Entity ${param.EntityName} not found in metadata`);
+                }
+                param.Fields = entity.Fields.map(f => f.Name);
+            }
+            // Check local cache if enabled
+            if (param.CacheLocal && localCacheManager_1.LocalCacheManager.Instance.IsInitialized) {
+                const fingerprint = localCacheManager_1.LocalCacheManager.Instance.GenerateRunViewFingerprint(param, this.InstanceConnectionString);
+                const cached = await localCacheManager_1.LocalCacheManager.Instance.GetRunViewResult(fingerprint);
+                if (cached) {
+                    const cachedViewResult = {
+                        Success: true,
+                        Results: cached.results,
+                        RowCount: cached.results.length,
+                        TotalRowCount: cached.results.length,
+                        ExecutionTime: 0,
+                        ErrorMessage: '',
+                        UserViewRunID: ''
+                    };
+                    // if needed this will transform each result into an entity object
+                    await this.TransformSimpleObjectToEntityObject(param, cachedViewResult, contextUser);
+                    cacheStatusMap.set(i, { status: 'hit', result: cachedViewResult });
+                    cachedResults.push(cachedViewResult);
+                    continue;
+                }
+                cacheStatusMap.set(i, { status: 'miss' });
+            }
+            else {
+                cacheStatusMap.set(i, { status: 'disabled' });
+            }
+            allCached = false;
+            uncachedParams.push(param);
+            cachedResults.push(null); // Placeholder for uncached
+        }
+        return {
+            telemetryEventId,
+            allCached,
+            cachedResults: allCached ? cachedResults.filter(r => r !== null) : undefined,
+            uncachedParams: allCached ? undefined : uncachedParams,
+            cacheStatusMap
+        };
+    }
+    /**
+     * Prepares smart cache check parameters for RunViews when CacheLocal is enabled.
+     * Instead of returning cached data immediately, this builds params to send to the server
+     * which will validate if the cache is current or return fresh data.
+     */
+    async prepareSmartCacheCheckParams(params, telemetryEventId, contextUser) {
+        const smartCacheCheckParams = [];
+        for (const param of params) {
+            // Entity status check
+            await this.EntityStatusCheck(param, 'PreRunViews');
+            // Handle entity_object result type - need all fields
+            if (param.ResultType === 'entity_object') {
+                const entity = this.Entities.find(e => e.Name.trim().toLowerCase() === param.EntityName?.trim().toLowerCase());
+                if (!entity) {
+                    throw new Error(`Entity ${param.EntityName} not found in metadata`);
+                }
+                param.Fields = entity.Fields.map(f => f.Name);
+            }
+            // Build the cache check param with optional cache status
+            let cacheStatus;
+            if (param.CacheLocal && localCacheManager_1.LocalCacheManager.Instance.IsInitialized) {
+                const fingerprint = localCacheManager_1.LocalCacheManager.Instance.GenerateRunViewFingerprint(param, this.InstanceConnectionString);
+                const cached = await localCacheManager_1.LocalCacheManager.Instance.GetRunViewResult(fingerprint);
+                if (cached) {
+                    cacheStatus = {
+                        maxUpdatedAt: cached.maxUpdatedAt,
+                        rowCount: cached.rowCount
+                    };
+                }
+            }
+            smartCacheCheckParams.push({
+                params: param,
+                cacheStatus
+            });
+        }
+        return {
+            telemetryEventId,
+            allCached: false, // Don't return cached directly - let server validate
+            useSmartCacheCheck: true,
+            smartCacheCheckParams,
+            cacheStatusMap: new Map()
+        };
+    }
+    /**
+     * Executes the smart cache check flow for RunViews.
+     * Calls RunViewsWithCacheCheck on the provider (if available) and processes the results,
+     * using cached data for 'current' items and fresh data for 'stale' items.
+     *
+     * Optimized to process all results in parallel using Promise.all for cache lookups,
+     * cache updates, and entity transformations.
+     */
+    async executeSmartCacheCheck(params, preResult, contextUser) {
+        // Cast to access RunViewsWithCacheCheck method
+        const provider = this;
+        // Execute the smart cache check
+        const response = await provider.RunViewsWithCacheCheck(preResult.smartCacheCheckParams, contextUser);
+        if (!response.success) {
+            // If the smart cache check failed, log and return empty results
+            (0, logging_1.LogError)(`SmartCacheCheck failed: ${response.errorMessage}`);
+            telemetryManager_1.TelemetryManager.Instance.EndEvent(preResult.telemetryEventId, {
+                smartCacheCheck: true,
+                success: false,
+                errorMessage: response.errorMessage
+            });
+            return params.map(() => ({
+                Success: false,
+                Results: [],
+                RowCount: 0,
+                TotalRowCount: 0,
+                ExecutionTime: 0,
+                ErrorMessage: response.errorMessage || 'SmartCacheCheck failed',
+                UserViewRunID: ''
+            }));
+        }
+        // Process all results in parallel
+        const processingPromises = params.map((param, i) => this.processSingleSmartCacheResult(param, i, response.results, contextUser));
+        const processedResults = await Promise.all(processingPromises);
+        // Aggregate telemetry stats
+        let cacheHits = 0;
+        let cacheMisses = 0;
+        for (const result of processedResults) {
+            if (result.cacheHit)
+                cacheHits++;
+            if (result.cacheMiss)
+                cacheMisses++;
+        }
+        // End telemetry
+        telemetryManager_1.TelemetryManager.Instance.EndEvent(preResult.telemetryEventId, {
+            smartCacheCheck: true,
+            success: true,
+            cacheHits,
+            cacheMisses,
+            batchSize: params.length
+        });
+        return processedResults.map(r => r.result);
+    }
+    /**
+     * Processes a single smart cache check result.
+     * Handles cache lookup for 'current' items and cache update for 'stale' items.
+     */
+    async processSingleSmartCacheResult(param, index, serverResults, contextUser) {
+        const checkResult = serverResults.find(r => r.viewIndex === index);
+        if (!checkResult) {
+            return {
+                result: {
+                    Success: false,
+                    Results: [],
+                    RowCount: 0,
+                    TotalRowCount: 0,
+                    ExecutionTime: 0,
+                    ErrorMessage: 'No result returned from server',
+                    UserViewRunID: ''
+                },
+                cacheHit: false,
+                cacheMiss: false
+            };
+        }
+        if (checkResult.status === 'current') {
+            // Cache is current - use cached data
+            const fingerprint = localCacheManager_1.LocalCacheManager.Instance.GenerateRunViewFingerprint(param, this.InstanceConnectionString);
+            const cached = await localCacheManager_1.LocalCacheManager.Instance.GetRunViewResult(fingerprint);
+            if (cached) {
+                const cachedResult = {
+                    Success: true,
+                    Results: cached.results,
+                    RowCount: cached.rowCount,
+                    TotalRowCount: cached.rowCount,
+                    ExecutionTime: 0,
+                    ErrorMessage: '',
+                    UserViewRunID: ''
+                };
+                // Transform to entity objects if needed
+                await this.TransformSimpleObjectToEntityObject(param, cachedResult, contextUser);
+                return { result: cachedResult, cacheHit: true, cacheMiss: false };
+            }
+            else {
+                // Cache miss - shouldn't happen but handle gracefully
+                return {
+                    result: {
+                        Success: false,
+                        Results: [],
+                        RowCount: 0,
+                        TotalRowCount: 0,
+                        ExecutionTime: 0,
+                        ErrorMessage: 'Cache marked current but no cached data found',
+                        UserViewRunID: ''
+                    },
+                    cacheHit: false,
+                    cacheMiss: false
+                };
+            }
+        }
+        else if (checkResult.status === 'stale') {
+            // Cache is stale - use fresh data and update cache
+            const freshResult = {
+                Success: true,
+                Results: checkResult.results || [],
+                RowCount: checkResult.rowCount || 0,
+                TotalRowCount: checkResult.rowCount || 0,
+                ExecutionTime: 0,
+                ErrorMessage: '',
+                UserViewRunID: ''
+            };
+            // Update the local cache with fresh data (don't await - fire and forget for performance)
+            if (param.CacheLocal && checkResult.maxUpdatedAt && localCacheManager_1.LocalCacheManager.Instance.IsInitialized) {
+                const fingerprint = localCacheManager_1.LocalCacheManager.Instance.GenerateRunViewFingerprint(param, this.InstanceConnectionString);
+                // Note: We don't await here to avoid blocking the response
+                // Cache update happens in background
+                localCacheManager_1.LocalCacheManager.Instance.SetRunViewResult(fingerprint, param, checkResult.results || [], checkResult.maxUpdatedAt, checkResult.rowCount).catch(e => (0, logging_1.LogError)(`Failed to update cache: ${e}`));
+            }
+            // Transform to entity objects if needed
+            await this.TransformSimpleObjectToEntityObject(param, freshResult, contextUser);
+            return { result: freshResult, cacheHit: false, cacheMiss: true };
+        }
+        else {
+            // Error status
+            return {
+                result: {
+                    Success: false,
+                    Results: [],
+                    RowCount: 0,
+                    TotalRowCount: 0,
+                    ExecutionTime: 0,
+                    ErrorMessage: checkResult.errorMessage || 'Unknown error',
+                    UserViewRunID: ''
+                },
+                cacheHit: false,
+                cacheMiss: false
+            };
+        }
+    }
+    /**
+     * Pre-processing hook for RunQuery.
+     * Handles telemetry and cache lookup.
+     * @param params - The query parameters
+     * @param contextUser - Optional user context
+     * @returns Pre-processing result with cache status and optional cached result
+     */
+    async PreRunQuery(params, contextUser) {
+        // Start telemetry tracking
+        const telemetryEventId = telemetryManager_1.TelemetryManager.Instance.StartEvent('RunQuery', 'ProviderBase.RunQuery', {
+            QueryID: params.QueryID,
+            QueryName: params.QueryName,
+            CategoryPath: params.CategoryPath,
+            CategoryID: params.CategoryID,
+            MaxRows: params.MaxRows,
+            StartRow: params.StartRow,
+            HasParameters: params.Parameters ? Object.keys(params.Parameters).length > 0 : false
+        }, contextUser?.ID);
+        // Query caching is handled internally by the provider's query cache mechanism
+        // We just return the telemetry info here - actual cache check happens in InternalRunQuery
+        return {
+            telemetryEventId,
+            cacheStatus: 'disabled', // Query caching is handled differently
+            cachedResult: undefined,
+            fingerprint: undefined
+        };
+    }
+    /**
+     * Pre-processing hook for RunQueries (batch).
+     * Handles telemetry for batch query operations.
+     * @param params - Array of query parameters
+     * @param contextUser - Optional user context
+     * @returns Pre-processing result
+     */
+    async PreRunQueries(params, contextUser) {
+        // Start telemetry tracking for batch operation
+        const telemetryEventId = telemetryManager_1.TelemetryManager.Instance.StartEvent('RunQuery', 'ProviderBase.RunQueries', {
+            BatchSize: params.length,
+            Queries: params.map(p => p.QueryName || p.QueryID).filter(Boolean)
+        }, contextUser?.ID);
+        // Query caching is handled internally by each query execution
+        return {
+            telemetryEventId,
+            allCached: false,
+            cachedResults: undefined,
+            uncachedParams: params,
+            cacheStatusMap: undefined
+        };
+    }
+    // ========================================================================
+    // POST-PROCESSING HOOKS
+    // ========================================================================
+    /**
+     * Post-processing hook for RunView.
+     * Handles result transformation, cache storage, and telemetry end.
+     * @param result - The view result
+     * @param params - The view parameters
+     * @param preResult - The pre-processing result
+     * @param contextUser - Optional user context
+     */
+    async PostRunView(result, params, preResult, contextUser) {
+        // Transform the result set into BaseEntity-derived objects, if needed
+        await this.TransformSimpleObjectToEntityObject(params, result, contextUser);
+        // Store in local cache if enabled and we have a successful result
+        if (params.CacheLocal && result.Success && preResult.fingerprint && localCacheManager_1.LocalCacheManager.Instance.IsInitialized) {
+            // Extract maxUpdatedAt from results if available
+            const maxUpdatedAt = this.extractMaxUpdatedAt(result.Results);
+            await localCacheManager_1.LocalCacheManager.Instance.SetRunViewResult(preResult.fingerprint, params, result.Results, maxUpdatedAt);
+        }
+        // End telemetry tracking with cache miss info
+        if (preResult.telemetryEventId) {
+            telemetryManager_1.TelemetryManager.Instance.EndEvent(preResult.telemetryEventId, {
+                cacheHit: false,
+                cacheStatus: preResult.cacheStatus,
+                resultCount: result.Results?.length ?? 0,
+                success: result.Success
+            });
+        }
+    }
+    /**
+     * Post-processing hook for RunViews (batch).
+     * Handles result transformation, cache storage, and telemetry end.
+     * @param results - Array of view results
+     * @param params - Array of view parameters
+     * @param preResult - The pre-processing result
+     * @param contextUser - Optional user context
+     */
+    async PostRunViews(results, params, preResult, contextUser) {
+        // Transform results in parallel
+        const promises = [];
+        for (let i = 0; i < results.length; i++) {
+            promises.push(this.TransformSimpleObjectToEntityObject(params[i], results[i], contextUser));
+            // Store in local cache if enabled
+            if (params[i].CacheLocal && results[i].Success && localCacheManager_1.LocalCacheManager.Instance.IsInitialized) {
+                const fingerprint = localCacheManager_1.LocalCacheManager.Instance.GenerateRunViewFingerprint(params[i], this.InstanceConnectionString);
+                const maxUpdatedAt = this.extractMaxUpdatedAt(results[i].Results);
+                promises.push(localCacheManager_1.LocalCacheManager.Instance.SetRunViewResult(fingerprint, params[i], results[i].Results, maxUpdatedAt));
+            }
+        }
+        await Promise.all(promises);
+        // End telemetry tracking with batch info
+        if (preResult.telemetryEventId) {
+            const totalResults = results.reduce((sum, r) => sum + (r.Results?.length ?? 0), 0);
+            const cachedCount = preResult.cacheStatusMap
+                ? [...preResult.cacheStatusMap.values()].filter(s => s.status === 'hit').length
+                : 0;
+            telemetryManager_1.TelemetryManager.Instance.EndEvent(preResult.telemetryEventId, {
+                cacheHit: false,
+                allCached: false,
+                batchSize: params.length,
+                cachedCount,
+                fetchedCount: params.length - cachedCount,
+                totalResultCount: totalResults
+            });
+        }
+    }
+    /**
+     * Post-processing hook for RunQuery.
+     * Handles cache storage and telemetry end.
+     * @param result - The query result
+     * @param params - The query parameters
+     * @param preResult - The pre-processing result
+     * @param contextUser - Optional user context
+     */
+    async PostRunQuery(result, params, preResult, contextUser) {
+        // Query caching is handled internally by the provider
+        // End telemetry tracking with cache miss info
+        if (preResult.telemetryEventId) {
+            telemetryManager_1.TelemetryManager.Instance.EndEvent(preResult.telemetryEventId, {
+                cacheHit: false,
+                cacheStatus: preResult.cacheStatus,
+                resultCount: result.Results?.length ?? 0,
+                success: result.Success
+            });
+        }
+    }
+    /**
+     * Post-processing hook for RunQueries (batch).
+     * Handles telemetry end.
+     * @param results - Array of query results
+     * @param params - Array of query parameters
+     * @param preResult - The pre-processing result
+     * @param contextUser - Optional user context
+     */
+    async PostRunQueries(results, params, preResult, contextUser) {
+        // Query caching is handled internally by each query execution
+        // End telemetry tracking with batch info
+        if (preResult.telemetryEventId) {
+            const totalResults = results.reduce((sum, r) => sum + (r.Results?.length ?? 0), 0);
+            const cachedCount = preResult.cacheStatusMap
+                ? [...preResult.cacheStatusMap.values()].filter(s => s.status === 'hit').length
+                : 0;
+            telemetryManager_1.TelemetryManager.Instance.EndEvent(preResult.telemetryEventId, {
+                cacheHit: false,
+                allCached: false,
+                batchSize: params.length,
+                cachedCount,
+                fetchedCount: params.length - cachedCount,
+                totalResultCount: totalResults
+            });
+        }
+    }
+    // ========================================================================
+    // CACHE HELPERS
+    // ========================================================================
+    /**
+     * Extracts the maximum __mj_UpdatedAt timestamp from a set of results.
+     * This is used for cache freshness checking.
+     * @param results - Array of result objects that may contain __mj_UpdatedAt
+     * @returns ISO string of the max timestamp, or current time if none found
+     */
+    extractMaxUpdatedAt(results) {
+        let maxDate = null;
+        for (const item of results) {
+            if (item && typeof item === 'object') {
+                const record = item;
+                // Check for __mj_UpdatedAt field (standard MJ timestamp field)
+                const updatedAt = record['__mj_UpdatedAt'] || record['UpdatedAt'];
+                if (updatedAt) {
+                    const date = updatedAt instanceof Date ? updatedAt : new Date(updatedAt);
+                    if (!isNaN(date.getTime()) && (!maxDate || date > maxDate)) {
+                        maxDate = date;
+                    }
+                }
+            }
+        }
+        return maxDate ? maxDate.toISOString() : new Date().toISOString();
+    }
+    /**
+     * Merges cached and fresh results for RunViews, maintaining original order.
+     * @param preResult - The pre-processing result with cache info
+     * @param freshResults - The fresh results from InternalRunViews
+     * @returns Combined results in original order
+     */
+    mergeCachedAndFreshResults(preResult, freshResults) {
+        if (!preResult.cacheStatusMap) {
+            return freshResults;
+        }
+        const merged = [];
+        let freshIndex = 0;
+        for (let i = 0; i < preResult.cacheStatusMap.size; i++) {
+            const cacheInfo = preResult.cacheStatusMap.get(i);
+            if (cacheInfo?.status === 'hit' && cacheInfo.result) {
+                merged.push(cacheInfo.result);
+            }
+            else {
+                merged.push(freshResults[freshIndex++]);
+            }
+        }
+        return merged;
+    }
+    /**
+     * Merges cached and fresh results for RunQueries, maintaining original order.
+     * @param preResult - The pre-processing result with cache info
+     * @param freshResults - The fresh results from InternalRunQueries
+     * @returns Combined results in original order
+     */
+    mergeQueryCachedAndFreshResults(preResult, freshResults) {
+        if (!preResult.cacheStatusMap) {
+            return freshResults;
+        }
+        const merged = [];
+        let freshIndex = 0;
+        for (let i = 0; i < preResult.cacheStatusMap.size; i++) {
+            const cacheInfo = preResult.cacheStatusMap.get(i);
+            if (cacheInfo?.status === 'hit' && cacheInfo.result) {
+                merged.push(cacheInfo.result);
+            }
+            else {
+                merged.push(freshResults[freshIndex++]);
+            }
+        }
+        return merged;
+    }
+    // ========================================================================
+    // LEGACY METHODS (kept for backward compatibility, will be removed)
+    // ========================================================================
+    /**
+     * @deprecated Use PreRunView instead. This method is kept for backward compatibility.
      */
     async PreProcessRunView(params, contextUser) {
+        // Start telemetry tracking
+        const eventId = telemetryManager_1.TelemetryManager.Instance.StartEvent('RunView', 'ProviderBase.RunView', {
+            EntityName: params.EntityName,
+            ViewID: params.ViewID,
+            ViewName: params.ViewName,
+            ExtraFilter: params.ExtraFilter,
+            OrderBy: params.OrderBy,
+            ResultType: params.ResultType,
+            MaxRows: params.MaxRows,
+            StartRow: params.StartRow,
+            _fromEngine: params._fromEngine
+        }, contextUser?.ID);
+        // Store on params object for retrieval in PostProcessRunView
+        params._telemetryEventId = eventId;
         await this.EntityStatusCheck(params, 'PreProcessRunView');
         // FIRST, if the resultType is entity_object, we need to run the view with ALL fields in the entity
         // so that we can get the data to populate the entity object with.
@@ -139,6 +859,12 @@ class ProviderBase {
     async PostProcessRunView(result, params, contextUser) {
         // Transform the result set into BaseEntity-derived objects, if needed
         await this.TransformSimpleObjectToEntityObject(params, result, contextUser);
+        // End telemetry tracking
+        const eventId = params._telemetryEventId;
+        if (eventId) {
+            telemetryManager_1.TelemetryManager.Instance.EndEvent(eventId);
+            delete params._telemetryEventId;
+        }
     }
     /**
      * Base class implementation for handling pre-processing of RunViews() each sub-class should call this
@@ -148,6 +874,17 @@ class ProviderBase {
      * @returns
      */
     async PreProcessRunViews(params, contextUser) {
+        // Start telemetry tracking for batch operation
+        const fromEngine = params.some(p => p._fromEngine);
+        const eventId = telemetryManager_1.TelemetryManager.Instance.StartEvent('RunView', 'ProviderBase.RunViews', {
+            BatchSize: params.length,
+            Entities: params.map(p => p.EntityName || p.ViewName || p.ViewID).filter(Boolean),
+            _fromEngine: fromEngine
+        }, contextUser?.ID);
+        // Store on first param for retrieval in PostProcessRunViews (using a special key to avoid collision)
+        if (params.length > 0) {
+            params[0]._telemetryBatchEventId = eventId;
+        }
         if (params && params.length > 0) {
             for (const param of params) {
                 this.EntityStatusCheck(param, 'PreProcessRunViews');
@@ -180,6 +917,12 @@ class ProviderBase {
             }
             // await the promises for all transformations
             await Promise.all(promises);
+            // End telemetry tracking for batch operation
+            const eventId = params[0]._telemetryBatchEventId;
+            if (eventId) {
+                telemetryManager_1.TelemetryManager.Instance.EndEvent(eventId);
+                delete params[0]._telemetryBatchEventId;
+            }
         }
     }
     /**
@@ -190,7 +933,7 @@ class ProviderBase {
      */
     async TransformSimpleObjectToEntityObject(param, result, contextUser) {
         // only if needed (e.g. ResultType==='entity_object'), transform the result set into BaseEntity-derived objects
-        if (param.ResultType === 'entity_object' && result && result.Success) {
+        if (param.ResultType === 'entity_object' && result && result.Success && result.Results?.length > 0) {
             // we need to transform each of the items in the result set into a BaseEntity-derived object
             // Create entities and load data in parallel for better performance
             const entityPromises = result.Results.map(async (item) => {
@@ -376,12 +1119,15 @@ class ProviderBase {
      */
     PostProcessEntityMetadata(entities, fields, fieldValues, permissions, relationships, settings) {
         const result = [];
+        // Sort entities alphabetically by name to ensure deterministic ordering
+        // This prevents non-deterministic output in CodeGen and other metadata consumers
+        const sortedEntities = entities.sort((a, b) => a.Name.localeCompare(b.Name));
         if (fieldValues && fieldValues.length > 0)
             for (let f of fields) {
                 // populate the field values for each field, if we have them
                 f.EntityFieldValues = fieldValues.filter(fv => fv.EntityFieldID === f.ID);
             }
-        for (let e of entities) {
+        for (let e of sortedEntities) {
             e.EntityFields = fields.filter(f => f.EntityID === e.ID).sort((a, b) => a.Sequence - b.Sequence);
             e.EntityPermissions = permissions.filter(p => p.EntityID === e.ID);
             e.EntityRelationships = relationships.filter(r => r.EntityID === e.ID);
@@ -936,7 +1682,6 @@ class ProviderBase {
                 const temp = JSON.parse(await ls.GetItem(this.LocalStoragePrefix + _a.localStorageAllMetadataKey)); // we now have a simple object for all the metadata
                 if (temp) {
                     // we have local metadata
-                    (0, logging_1.LogStatus)('Metadata loaded from local storage');
                     const metadata = MetadataFromSimpleObject(temp, this); // create a new object to start this up
                     this.UpdateLocalMetadata(metadata);
                 }