@memberjunction/core 6.2.0-edge.5 → 6.2.0-edge.6

package/dist/generic/baseEngine.js

@@ -206,6 +206,12 @@ export class BaseEngine extends BaseSingleton {
         this._externalChangeReloads = new Map();
         this._entityEventDebounceTime = 1500; // Default debounce time in milliseconds (1.5 seconds)
         this._eventRefreshRetryTimers = new Map();
+        /**
+         * Maps normalized entity names (`entityName.trim().toLowerCase()`) to dataset item properties
+         * loaded via `DatasetResultHandling === 'single_property'`, allowing in-place auto-refresh of
+         * dataset-backed engines (such as `TemplateEngineBase`) on entity save/delete events.
+         */
+        this._datasetItemMappings = new Map();
         /** Configs waiting for the cache manager to initialize before their callbacks can register. */
         this._deferredCacheCallbackConfigs = null;
     }
@@ -676,11 +682,16 @@ export class BaseEngine extends BaseSingleton {
                 const matchingConfigs = this._metadataConfigs.filter((config) => {
                     return config.AutoRefresh && config.EntityName && config.EntityName.trim().toLowerCase() === eName;
                 });
-                if (matchingConfigs.length === 0) {
+                const matchingDatasetItems = (this._datasetItemMappings.get(eName) ?? []).filter(m => m.config.AutoRefresh !== false);
+                if (matchingConfigs.length === 0 && matchingDatasetItems.length === 0) {
                     return true;
                 }
-                // Check if ALL matching configs can use immediate mutation
-                const allCanUseImmediate = matchingConfigs.every(config => this.canUseImmediateMutation(config));
+                // Check if ALL matching entity configs can use immediate mutation. A saved object
+                // that lacks columns (its saver could not read them) would put a narrowed row into
+                // an engine every user reads, so that save takes the full-refresh path instead,
+                // which reloads the row as this engine's own user.
+                const allCanUseImmediate = matchingConfigs.every(config => this.canUseImmediateMutation(config))
+                    && this.savedRowIsComplete(event);
                 if (allCanUseImmediate) {
                     const applyAll = async () => {
                         // mutation requires await because the entity must be cloned (with its
@@ -688,6 +699,9 @@ export class BaseEngine extends BaseSingleton {
                         for (const config of matchingConfigs) {
                             await this.applyImmediateMutation(config, event);
                         }
+                        if (matchingDatasetItems.length > 0) {
+                            await this.applyDatasetItemMutations(matchingDatasetItems, event);
+                        }
                     };
                     // The entity raises save/delete as soon as its own write returns, while an
                     // enclosing transaction may still be open. Mutating the cache now would keep a
@@ -714,6 +728,21 @@ export class BaseEngine extends BaseSingleton {
                     return true;
                 }
                 else {
+                    if (matchingDatasetItems.length > 0) {
+                        const provider = event.baseEntity.ProviderToUse;
+                        if (provider instanceof DatabaseProviderBase && provider.TransactionDepth > 0) {
+                            const token = provider.CapturePostCommitToken();
+                            const savedKey = event.type === 'save' ? event.baseEntity.PrimaryKey.ToString() : null;
+                            provider.RunAfterCommit(async () => {
+                                if (savedKey !== null && event.baseEntity.PrimaryKey.ToString() !== savedKey)
+                                    return;
+                                await this.applyDatasetItemMutations(matchingDatasetItems, event);
+                            }, `BaseEngine dataset cache mutation for ${eName}`, token);
+                        }
+                        else {
+                            await this.applyDatasetItemMutations(matchingDatasetItems, event);
+                        }
+                    }
                     // At least one config requires full refresh, use debouncing
                     return this.DebounceIndividualBaseEntityEvent(event);
                 }
@@ -967,7 +996,9 @@ export class BaseEngine extends BaseSingleton {
                     const needingWork = classified.filter(c => c.disposition.action === 'refresh');
                     if (needingWork.length > 0) {
                         // Check if we can use immediate array mutation instead of running a view
-                        if (this.canUseImmediateMutation(config)) {
+                        // A save carrying a row with missing columns can't replace an engine row
+                        // in place (see savedRowIsComplete), so the whole window refreshes instead.
+                        if (this.canUseImmediateMutation(config) && needingWork.every(c => this.savedRowIsComplete(c.event))) {
                             // Apply, in order, every event the array hasn't seen yet
                             for (const c of needingWork) {
                                 await this.applyImmediateMutation(config, c.event);
@@ -1032,7 +1063,11 @@ export class BaseEngine extends BaseSingleton {
     classifyEventForConfig(config, event) {
         if (event.type === 'save') {
             if (event.saveSubType === 'update' || event.saveSubType === 'create') {
-                if (this.isEntityAlreadyInArray(config, event.baseEntity)) {
+                // When AlternateBaseView is set on the config, the SQL view applies a canonical
+                // WHERE/JOIN predicate — an in-memory update can cause the record to fall out of
+                // the alternate view (e.g. Status changed from 'Active' to 'Inactive'), so we
+                // must refresh from the database rather than only notifying in place.
+                if (!config.AlternateBaseView && this.isEntityAlreadyInArray(config, event.baseEntity)) {
                     return { action: 'notify', changeType: event.saveSubType === 'create' ? 'add' : 'update' };
                 }
             }
@@ -1217,6 +1252,11 @@ export class BaseEngine extends BaseSingleton {
         if (config.Filter) {
             return false;
         }
+        // An AlternateBaseView applies a canonical SQL WHERE/JOIN in the database view;
+        // immediate in-memory mutations cannot evaluate that SQL predicate.
+        if (config.AlternateBaseView) {
+            return false;
+        }
         // If there's an OrderBy, we can't safely do immediate mutations because:
         // - For creates: we'd need to insert at the correct position
         // - For updates: the entity might need to move to a different position
@@ -1255,6 +1295,21 @@ export class BaseEngine extends BaseSingleton {
         // it means the subclass has overridden it
         return instanceProto.AdditionalLoading !== baseProto.AdditionalLoading;
     }
+    /**
+     * Whether a save event's entity carries every column, so it can replace an engine row in
+     * place. Deletes and non-save events always qualify.
+     */
+    savedRowIsComplete(event) {
+        if (event.type !== 'save' || !event.baseEntity) {
+            return true;
+        }
+        const entity = event.baseEntity;
+        // Asked of the object directly, so no throwaway GetAll() row is built per event. An object
+        // that is not a BaseEntity (a test double) is judged on its row, as before.
+        return typeof entity.HoldsEveryField === 'function'
+            ? entity.HoldsEveryField()
+            : LocalCacheManager.RowHasEveryField(entity.EntityInfo, entity.GetAll());
+    }
     /**
      * Applies an immediate array mutation based on the entity event type.
      * This is faster than running a full view refresh for simple add/update/delete operations.
@@ -1404,16 +1459,9 @@ export class BaseEngine extends BaseSingleton {
         if (cache.IsBatchingEntityEvents(entity?.ProviderToUse) || cache.WasTakenByEntityEventBatch(event)) {
             return;
         }
-        // Get the connection string from the provider for fingerprint generation
-        // The provider is needed because fingerprints include connection prefix
-        const provider = this.ProviderToUse;
-        let connectionString;
-        if (provider && 'InstanceConnectionString' in provider) {
-            connectionString = provider.InstanceConnectionString;
-        }
-        // Use the shared builder so the fingerprint matches what LoadSingleEntityConfig
-        // and RegisterCacheChangeCallbacks produce — prevents silent cache-slot mismatches
-        const fingerprint = LocalCacheManager.Instance.GenerateRunViewFingerprint(this.BuildRunViewParamsForConfig(config), connectionString);
+        // The same builder as LoadSingleEntityConfig and RegisterCacheChangeCallbacks, so the
+        // slot maintained here is the one this engine reads and listens on.
+        const fingerprint = this.configFingerprint(config);
         // Build CompositeKey from the entity's primary key fields
         const key = entity.PrimaryKey;
         if (!key || key.KeyValuePairs.length === 0 || key.KeyValuePairs.some(kv => kv.Value == null)) {
@@ -1435,6 +1483,12 @@ export class BaseEngine extends BaseSingleton {
         }
         else {
             const entityData = entity.GetAll();
+            // A row-filtered or field-secured slot, or a saved row missing columns, cannot take the
+            // saver's values in place: clear it and let the next read refill it.
+            if (!LocalCacheManager.Instance.CanUpsertRowIntoSlot(fingerprint, entity.EntityInfo, entityData)) {
+                await LocalCacheManager.Instance.InvalidateRunViewResult(fingerprint);
+                return;
+            }
             await LocalCacheManager.Instance.UpsertSingleEntity(fingerprint, entityData, key, updatedAt);
         }
     }
@@ -1498,6 +1552,7 @@ export class BaseEngine extends BaseSingleton {
         // now, break up the configs into two chunks, datasets and views of entities so we can load all the views in a single network call via RunViews()
         const entityConfigs = this._metadataConfigs.filter(c => c.Type === 'entity');
         const datasetConfigs = this._metadataConfigs.filter(c => c.Type === 'dataset');
+        this.WarnAboutFieldSecuredEntities(entityConfigs);
         // All-or-nothing permission check: if the user lacks read access on ANY
         // entity config, skip ALL entity configs for this engine. Returns the
         // original array unchanged when permissions pass, or an empty array when
@@ -1508,6 +1563,35 @@ export class BaseEngine extends BaseSingleton {
         // Register cross-server cache change callbacks for entity configs
         this.RegisterCacheChangeCallbacks(entityConfigs);
     }
+    /** Engine-class and entity pairs already warned about by {@link WarnAboutFieldSecuredEntities}. */
+    static { this._fieldSecurityWarned = new Set(); }
+    /**
+     * On a server, says once per engine class and entity when an entity this engine caches has
+     * field-level security (its own, or an IS-A ancestor's). Changes nothing about the load.
+     *
+     * A server-side engine loads as the system user (see {@link ResolveContextUser}), so its
+     * cache holds every column, including ones some users are denied. That is correct for a
+     * process-wide cache, and it makes every path that hands engine data to a person responsible
+     * for projecting it to that person first.
+     */
+    WarnAboutFieldSecuredEntities(entityConfigs) {
+        const provider = this.ProviderToUse;
+        if (provider?.ProviderType !== ProviderType.Database) {
+            return;
+        }
+        for (const config of entityConfigs) {
+            const entityInfo = config.EntityName ? provider.EntityByName(config.EntityName) : undefined;
+            if (!entityInfo?.FieldLevelSecurityApplies) {
+                continue;
+            }
+            const key = `${this.constructor.name}|${entityInfo.Name}`.toLowerCase();
+            if (BaseEngine._fieldSecurityWarned.has(key)) {
+                continue;
+            }
+            BaseEngine._fieldSecurityWarned.add(key);
+            LogStatus(`${this.constructor.name}: '${entityInfo.Name}' has field-level security. Engine data is loaded as the system user and holds every column; project it for the acting user before it reaches a person.`);
+        }
+    }
     /**
      * All-or-nothing permission gate: checks `CanRead` on every entity config. If ANY
      * entity is denied, ALL configs are skipped — the engine is marked permission-constrained
@@ -1659,14 +1743,8 @@ export class BaseEngine extends BaseSingleton {
      * IgnoreMaxRows, IncludeBinaryFields) are always consistent — preventing cache key mismatches that break
      * cross-server invalidation via Redis pub/sub and local cache upsert/remove operations.
      *
-     * **Row-level security is not part of the fingerprints built from these params.** The engine
-     * builds them with `GenerateRunViewFingerprint(params, connection)`, without the RLS clause the
-     * provider adds for the reading user. On a server that is correct: engines load as the system
-     * user, whose RLS clause is empty, so the provider's fingerprint for the same read matches. An
-     * engine loaded by an RLS-scoped user (possible on a client) would compute an unscoped
-     * fingerprint for a slot the provider stored under a scoped one, so its cache callbacks and
-     * `syncLocalCacheForConfig` would target a different slot. Pass the RLS clause here if such an
-     * engine is ever needed.
+     * The slot fingerprint for these params also carries the engine user's row-level-security
+     * and field-security segments; see {@link configFingerprint}.
      */
     BuildRunViewParamsForConfig(config, bypassCache = false) {
         return {
@@ -1674,6 +1752,7 @@ export class BaseEngine extends BaseSingleton {
             ResultType: config.ResultType || this.EngineDefaultResultType,
             ExtraFilter: config.Filter,
             OrderBy: config.OrderBy,
+            ...(config.AlternateBaseView ? { AlternateBaseView: config.AlternateBaseView } : {}),
             IgnoreMaxRows: true, // Engines always need ALL data — bypass entity-level UserViewMaxRows caps
             _fromEngine: true, // Mark as engine-initiated to avoid false positive telemetry warnings
             CacheLocal: config.CacheLocal,
@@ -1834,6 +1913,58 @@ export class BaseEngine extends BaseSingleton {
             }
         }
     }
+    /**
+     * Applies an immediate in-place mutation to dataset item arrays when a constituent entity is saved or deleted,
+     * then invokes {@link AdditionalLoading} so derived associations (e.g. Template Content / Params) stay current.
+     */
+    async applyDatasetItemMutations(mappings, event) {
+        const entity = event.baseEntity;
+        let mutated = false;
+        const notifiedProperties = new Set();
+        for (const mapping of mappings) {
+            const container = this[mapping.config.PropertyName];
+            const currentData = container?.[mapping.itemCode];
+            if (!Array.isArray(currentData)) {
+                continue;
+            }
+            if (event.type === 'save') {
+                const provider = this.ProviderToUse;
+                if (!provider)
+                    continue;
+                const cached = await provider.GetEntityObject(mapping.entityName, this._contextUser);
+                if (!cached)
+                    continue;
+                await cached.LoadFromData(entity.GetAll());
+                const existsByRef = currentData.indexOf(entity) >= 0;
+                if (!existsByRef) {
+                    const index = this.findEntityIndexByPrimaryKeys(currentData, entity);
+                    if (index >= 0) {
+                        currentData[index] = cached;
+                    }
+                    else {
+                        currentData.push(cached);
+                    }
+                }
+                mutated = true;
+                notifiedProperties.add(mapping.config.PropertyName);
+            }
+            else if (event.type === 'delete') {
+                const oldValues = event.payload?.OldValues;
+                const index = this.indexOfEntityByRefOrKey(currentData, entity, oldValues);
+                if (index >= 0) {
+                    currentData.splice(index, 1);
+                    mutated = true;
+                    notifiedProperties.add(mapping.config.PropertyName);
+                }
+            }
+        }
+        if (mutated) {
+            await this.AdditionalLoading(this._contextUser);
+            for (const propName of notifiedProperties) {
+                this.emitPropertyChange(propName);
+            }
+        }
+    }
     /**
      * Handles the process of loading a single config of type 'dataset'.
      * @param config
@@ -1853,7 +1984,7 @@ export class BaseEngine extends BaseSingleton {
             await p.CacheDataset(config.DatasetName, config.DatasetItemFilters, result);
         }
         else {
-            result = await p.GetAndCacheDatasetByName(config.DatasetName, config.DatasetItemFilters);
+            result = await p.GetAndCacheDatasetByName(config.DatasetName, config.DatasetItemFilters, contextUser);
         }
         if (!result) {
             const errorMsg = `GetAndCacheDatasetByName("${config.DatasetName}") returned undefined/null — provider: ${p?.constructor?.name}`;
@@ -1880,18 +2011,31 @@ export class BaseEngine extends BaseSingleton {
         if (result.Success) {
             if (config.AddToObject !== false) {
                 if (config.DatasetResultHandling === 'single_property') {
+                    // Clear previous dataset item mappings for this property before re-indexing
+                    for (const [key, list] of this._datasetItemMappings.entries()) {
+                        const filtered = list.filter(m => m.config.PropertyName !== config.PropertyName);
+                        if (filtered.length === 0) {
+                            this._datasetItemMappings.delete(key);
+                        }
+                        else if (filtered.length !== list.length) {
+                            this._datasetItemMappings.set(key, filtered);
+                        }
+                    }
                     const singleObject = {};
-                    for (const item of result.Results) {
-                        //convert the results to entity objects before
-                        //adding them to the singleObject
-                        const entities = [];
-                        for (const entityData of item.Results) {
+                    await Promise.all(result.Results.map(async (item) => {
+                        const entities = await Promise.all(item.Results.map(async (entityData) => {
                             const entity = await p.GetEntityObject(item.EntityName, contextUser);
                             await entity.LoadFromData(entityData);
-                            entities.push(entity);
-                        }
+                            return entity;
+                        }));
                         singleObject[item.Code] = entities;
-                    }
+                        if (item.EntityName && item.Code) {
+                            const normName = item.EntityName.trim().toLowerCase();
+                            const existing = this._datasetItemMappings.get(normName) ?? [];
+                            existing.push({ config, itemCode: item.Code, entityName: item.EntityName });
+                            this._datasetItemMappings.set(normName, existing);
+                        }
+                    }));
                     this[config.PropertyName] = singleObject;
                 }
                 else {
@@ -2337,11 +2481,26 @@ export class BaseEngine extends BaseSingleton {
         // read-modify-write of this slot, and an unlocked replace would clobber it.
         await cache.ReplaceRunViewResultLocked(this.configFingerprint(config), params, plainRows, maxUpdatedAt, plainRows.length, this.ProviderToUse);
     }
-    /** The cache fingerprint of a config's slot, as {@link RegisterCacheChangeCallbacks} computes it. */
+    /**
+     * The cache fingerprint of a config's slot: the one {@link RegisterCacheChangeCallbacks} listens
+     * on, {@link syncLocalCacheForConfig} maintains and {@link storeConfigRows} writes.
+     *
+     * Built by the provider for this engine's user, with that user's row-level-security and
+     * field-security segments, so it names the same slot the provider's own RunView read used. An
+     * engine running as a restricted user holds only what that user may see; without the segments
+     * its rows would be written into, and its callbacks registered on, the slot unrestricted
+     * readers share.
+     */
     configFingerprint(config) {
+        const params = this.BuildRunViewParamsForConfig(config);
         const provider = this.RunViewProviderToUse;
-        const connectionPrefix = provider instanceof ProviderBase ? provider.InstanceConnectionString : undefined;
-        return LocalCacheManager.Instance.GenerateRunViewFingerprint(this.BuildRunViewParamsForConfig(config), connectionPrefix);
+        if (provider instanceof ProviderBase) {
+            return provider.ComputeRunViewCacheFingerprint(params, this._contextUser);
+        }
+        const connection = provider && 'InstanceConnectionString' in provider
+            ? provider.InstanceConnectionString
+            : undefined;
+        return LocalCacheManager.Instance.GenerateRunViewFingerprint(params, connection);
     }
     /**
      * Snapshot of what this engine holds: per property, the row count, newest `__mj_UpdatedAt`,