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

package/dist/generic/databaseProviderBase.js

@@ -9,7 +9,8 @@ import { CompositeKey } from "./compositeKey.js";
 import { LogError } from "./logging.js";
 import { LocalCacheManager } from "./localCacheManager.js";
 import { AssertClientInputWritableForUser } from "./entityValueFieldSecurity.js";
-import { FormatBinaryChangeValue, ScanSQLForScreening, SQLExpressionValidator, uuidv4 } from "@memberjunction/global";
+import { CanonicalPrimaryKeyValue } from "./util.js";
+import { FormatBinaryChangeValue, ScanSQLForScreening, SQLExpressionValidator, uuidv4, EscapeSQLString } from "@memberjunction/global";
 import { GetDialect } from "@memberjunction/sql-dialect";
 // Re-export PlatformSQL types from their canonical location for backward compatibility
 export { IsPlatformSQL } from "./platformSQL.js";
@@ -321,6 +322,28 @@ export class DatabaseProviderBase extends ProviderBase {
     get MJCoreSchemaName() {
         return this.ConfigData?.MJCoreSchemaName ?? '__mj';
     }
+    /**
+     * Builds a batched UNION ALL query probing all `childEntities`' `BaseView`s for a set
+     * of parent primary-key values (`WHERE pk IN (...)`), returning `(EntityName, RecordPK, Priority)`.
+     * Dialect providers override this to use platform-native string-literal and CAST syntax.
+     */
+    BuildChildDiscoveryBatchSQL(childEntities, recordPKValues) {
+        if (recordPKValues.length === 0)
+            return '';
+        const escapedKeys = recordPKValues
+            .map(v => `'${EscapeSQLString(String(v))}'`)
+            .join(', ');
+        const unionParts = childEntities
+            .filter(child => child.PrimaryKeys.length > 0)
+            .map((child, idx) => {
+            const schema = child.SchemaName || this.MJCoreSchemaName || '__mj';
+            const sourceRef = this.QuoteSchemaAndView(schema, child.BaseView);
+            const pkRef = this.QuoteIdentifier(child.FirstPrimaryKey.Name); // first-pk-ok: IS-A children share the parent's single key
+            const escapedName = `'${EscapeSQLString(child.Name)}'`;
+            return `SELECT ${escapedName} AS ${this.QuoteIdentifier('EntityName')}, CAST(${pkRef} AS VARCHAR(255)) AS ${this.QuoteIdentifier('RecordPK')}, ${idx + 1} AS ${this.QuoteIdentifier('Priority')} FROM ${sourceRef} WHERE ${pkRef} IN (${escapedKeys})`;
+        });
+        return unionParts.length > 0 ? unionParts.join(' UNION ALL ') : '';
+    }
     /**
      * Combined regex covering UUID functions from ALL platforms.
      * Used by the static convenience method for code that doesn't have a provider instance.
@@ -585,6 +608,91 @@ export class DatabaseProviderBase extends ProviderBase {
         }
         return [];
     }
+    static { this.DEFAULT_ISA_DISCOVERY_BATCH_CHUNK_SIZE = 500; }
+    /**
+     * Maximum number of parent primary keys included in a single `BuildChildDiscoveryBatchSQL`
+     * `WHERE PK IN (...)` statement inside {@link FindISAChildEntitiesBatch}.
+     */
+    get ISADiscoveryBatchChunkSize() {
+        return DatabaseProviderBase.DEFAULT_ISA_DISCOVERY_BATCH_CHUNK_SIZE;
+    }
+    /**
+     * Batch-discovers IS-A child entity types for multiple parent primary keys in a single
+     * UNION ALL SQL query (chunked at {@link ISADiscoveryBatchChunkSize} keys per statement to
+     * stay well within SQL limits).
+     */
+    async FindISAChildEntitiesBatch(entityInfo, recordPKValues, contextUser) {
+        const resultMap = new Map();
+        const childEntities = entityInfo.ChildEntities;
+        if (childEntities.length === 0 || recordPKValues.length === 0) {
+            return resultMap;
+        }
+        // IS-A children share the parent's single key, so the parent's key type decides how values
+        // are canonicalized (UUIDs case-insensitively, anything else by exact text).
+        const pkIsUuid = Boolean(entityInfo.FirstPrimaryKey?.IsUniqueIdentifier); // first-pk-ok: IS-A children share the parent's single key
+        const uniquePKs = this.deduplicateCanonicalPKs(recordPKValues, pkIsUuid);
+        if (uniquePKs.length === 0) {
+            return resultMap;
+        }
+        const priorityByChildName = new Map();
+        for (let i = 0; i < childEntities.length; i++) {
+            priorityByChildName.set(childEntities[i].Name.toLowerCase(), i + 1);
+        }
+        const chunkSize = this.ISADiscoveryBatchChunkSize;
+        const collected = new Map();
+        for (let start = 0; start < uniquePKs.length; start += chunkSize) {
+            const chunk = uniquePKs.slice(start, start + chunkSize);
+            await this.collectISAChildBatchChunk(childEntities, chunk, pkIsUuid, priorityByChildName, collected, contextUser);
+        }
+        for (const [pkKey, entries] of collected) {
+            entries.sort((a, b) => a.priority - b.priority);
+            const names = [];
+            for (const entry of entries) {
+                if (!names.includes(entry.name)) {
+                    names.push(entry.name);
+                }
+            }
+            resultMap.set(pkKey, names);
+        }
+        return resultMap;
+    }
+    deduplicateCanonicalPKs(recordPKValues, pkIsUuid) {
+        const uniquePKs = [];
+        const seen = new Set();
+        for (const rawPk of recordPKValues) {
+            if (!rawPk)
+                continue;
+            const norm = CanonicalPrimaryKeyValue(String(rawPk), pkIsUuid);
+            if (!seen.has(norm)) {
+                seen.add(norm);
+                uniquePKs.push(String(rawPk).trim());
+            }
+        }
+        return uniquePKs;
+    }
+    async collectISAChildBatchChunk(childEntities, chunk, pkIsUuid, priorityByChildName, collected, contextUser) {
+        const batchSQL = this.BuildChildDiscoveryBatchSQL(childEntities, chunk);
+        if (!batchSQL)
+            return;
+        const rows = await this.ExecuteSQL(batchSQL, undefined, undefined, contextUser);
+        if (!rows || rows.length === 0)
+            return;
+        for (const row of rows) {
+            const entityName = row.EntityName ?? row.ChildEntityName;
+            if (!entityName || row.RecordPK == null)
+                continue;
+            const pkKey = CanonicalPrimaryKeyValue(String(row.RecordPK), pkIsUuid);
+            const priority = typeof row.Priority === 'number'
+                ? row.Priority
+                : (priorityByChildName.get(entityName.toLowerCase()) ?? Number.MAX_SAFE_INTEGER);
+            let bucket = collected.get(pkKey);
+            if (!bucket) {
+                bucket = [];
+                collected.set(pkKey, bucket);
+            }
+            bucket.push({ name: entityName, priority });
+        }
+    }
     /**
      * Checks whether a given entity matches the target name, or is an ancestor
      * of the target (i.e., the target is somewhere in its descendant sub-tree).
@@ -959,6 +1067,27 @@ export class DatabaseProviderBase extends ProviderBase {
     async OnBeforeSaveExecute(_entity, _user, _options, _context) {
         /* no-op by default */
     }
+    /**
+     * Returns true when `Save()` must enlist {@link OnDurableAfterSaveExecute} transactionally
+     * (wrapping direct saves in an {@link EntityTransactionScope}, and awaiting durable action
+     * submission inside `TransactionGroup` save callbacks before group completion).
+     *
+     * Default: `false` (zero extra transaction overhead on ordinary entity saves).
+     */
+    async ShouldEnlistSaveInTransaction(_entity, _user, _options, _isNewRecord) {
+        return false;
+    }
+    /**
+     * Awaited immediately after the save SQL succeeds (inside direct `Save()`'s
+     * {@link EntityTransactionScope} before commit, or inside a `TransactionGroup` item's completion
+     * callback after hydrating DB-generated PKs and before {@link OnAfterSaveExecute}) when
+     * {@link ShouldEnlistSaveInTransaction} returned `true`.
+     * Used by `GenericDatabaseProvider` to enlist durable after-save entity actions atomically in the
+     * same SQL transaction as the entity write.
+     */
+    async OnDurableAfterSaveExecute(_entity, _user, _options, _context) {
+        /* no-op by default */
+    }
     /**
      * Called after a successful save (both direct and transaction-callback paths).
      * Intentionally synchronous (fire-and-forget) — SQL Server overrides to dispatch
@@ -1485,8 +1614,11 @@ export class DatabaseProviderBase extends ProviderBase {
                 this.OnResumeRefresh();
             }
         };
+        let transactionPreprocessingRegistered = false;
+        let transactionReadyRaised = false;
         try {
             entity.RegisterTransactionPreprocessing();
+            transactionPreprocessingRegistered = Boolean(entity.TransactionGroup);
             // External-data-source entities are read-only — MJ is never the system of record for
             // remote data. Refuse writes at the provider layer so the guarantee holds regardless of
             // the generated base class (ReadOnlyExternalBaseEntity covers the normal path — returning
@@ -1617,6 +1749,7 @@ export class DatabaseProviderBase extends ProviderBase {
                 if (entity.TransactionGroup && !bReplay) {
                     // ---- Transaction Group path ----
                     entity.RaiseReadyForTransaction();
+                    transactionReadyRaised = true;
                     suspendRefresh();
                     const extraData = this.GetTransactionExtraData(entity);
                     Object.defineProperty(extraData, 'simpleSQLFallback', {
@@ -1625,72 +1758,137 @@ export class DatabaseProviderBase extends ProviderBase {
                         configurable: true,
                     });
                     extraData.entityName = entity.EntityInfo.Name;
-                    entity.TransactionGroup.AddTransaction(new TransactionItem(entity, entityResult.Type === 'create' ? 'Create' : 'Update', sqlDetails.literalSQL ?? sqlDetails.fullSQL, sqlDetails.literalSQL ? null : (sqlDetails.parameters ?? null), extraData, (transactionResult, success) => {
+                    entity.TransactionGroup.AddTransaction(new TransactionItem(entity, entityResult.Type === 'create' ? 'Create' : 'Update', sqlDetails.literalSQL ?? sqlDetails.fullSQL, sqlDetails.literalSQL ? null : (sqlDetails.parameters ?? null), extraData, async (transactionResult, success) => {
                         resumeRefresh();
                         entityResult.EndedAt = new Date();
                         if (success && transactionResult) {
+                            if (bNewRecord) {
+                                let hydratedPk = false;
+                                for (const pkField of entity.EntityInfo.PrimaryKeys) {
+                                    const fieldObj = entity.Fields.find((f) => f.Name === pkField.Name);
+                                    if (fieldObj &&
+                                        (fieldObj.Value === null || fieldObj.Value === undefined) &&
+                                        transactionResult[pkField.Name] != null) {
+                                        fieldObj.Value = transactionResult[pkField.Name];
+                                        hydratedPk = true;
+                                    }
+                                }
+                                if (hydratedPk) {
+                                    entity.PrimaryKey.LoadFromEntityFields(entity.PrimaryKeys);
+                                }
+                            }
+                            if (await this.ShouldEnlistSaveInTransaction(entity, user, options, bNewRecord)) {
+                                await this.OnDurableAfterSaveExecute(entity, user, options, saveContext);
+                            }
+                            if (preSaveValues) {
+                                for (const [key, val] of Object.entries(preSaveValues)) {
+                                    if (!(key in transactionResult)) {
+                                        transactionResult[key] = val;
+                                    }
+                                }
+                                Object.defineProperty(transactionResult, '__mj_preMerged', {
+                                    value: true,
+                                    enumerable: false,
+                                    configurable: true,
+                                });
+                            }
+                            const patches = await this.OnSaveCompleted(entity, sqlDetails, user, options, saveContext);
+                            if (patches) {
+                                Object.assign(transactionResult, patches);
+                            }
                             this.OnAfterSaveExecute(entity, user, options, saveContext);
                             entityResult.Success = true;
-                            const mergedResult = preSaveValues
-                                ? { ...preSaveValues, ...transactionResult }
-                                : transactionResult;
-                            entityResult.NewValues = this.MapTransactionResultToNewValues(mergedResult);
+                            entityResult.NewValues = this.MapTransactionResultToNewValues(transactionResult);
                         }
                         else {
                             entityResult.Success = false;
-                            entityResult.Message = 'Transaction Failed';
+                            if (!entityResult.Message) {
+                                entityResult.Message =
+                                    transactionResult instanceof Error ? transactionResult.message : 'Transaction Failed';
+                            }
                         }
                     }));
                     return true;
                 }
                 else {
                     // ---- Direct execution path ----
+                    const enlistInTx = !bReplay && await this.ShouldEnlistSaveInTransaction(entity, user, options, bNewRecord);
+                    const saveTxScope = enlistInTx ? await this.BeginEntityTransaction() : null;
+                    let saveTxCommitted = false;
                     suspendRefresh();
                     let result;
-                    if (bReplay) {
-                        result = [entity.GetAll()];
-                    }
-                    else {
-                        const execOptions = this.BuildSaveExecuteOptions(entity, sqlDetails);
-                        const rawResult = await this.ExecuteSQL(sqlDetails.fullSQL, sqlDetails.parameters ?? undefined, execOptions, user);
-                        result = await this.PostProcessRows(rawResult, entity.EntityInfo, user);
-                    }
-                    resumeRefresh();
-                    entityResult.EndedAt = new Date();
-                    if (result && result.length > 0) {
-                        this.OnAfterSaveExecute(entity, user, options, saveContext);
-                        entityResult.Success = true;
-                        // In 'datestamps_only' mode, the SP/query returned only the PK and
-                        // __mj_CreatedAt/__mj_UpdatedAt columns. Merge those returned values
-                        // onto the pre-save snapshot so caller-set fields remain intact without
-                        // falsely marking concurrent in-flight mutations as clean.
-                        let mergedRow;
-                        if (preSaveValues) {
-                            mergedRow = { ...preSaveValues, ...result[0] };
-                            Object.defineProperty(mergedRow, '__mj_preMerged', {
-                                value: true,
-                                enumerable: false,
-                                configurable: true,
-                            });
+                    try {
+                        if (bReplay) {
+                            result = [entity.GetAll()];
                         }
                         else {
-                            mergedRow = result[0];
+                            const execOptions = this.BuildSaveExecuteOptions(entity, sqlDetails);
+                            const rawResult = await this.ExecuteSQL(sqlDetails.fullSQL, sqlDetails.parameters ?? undefined, execOptions, user);
+                            result = await this.PostProcessRows(rawResult, entity.EntityInfo, user);
                         }
-                        // OnSaveCompleted may return patch fields (e.g., updated lat/lng
-                        // from geocoding) that need to be merged onto the SP result before
-                        // the entity loads the data via finalizeSave().
-                        const patches = await this.OnSaveCompleted(entity, sqlDetails, user, options, saveContext);
-                        if (patches) {
-                            Object.assign(mergedRow, patches);
+                        resumeRefresh();
+                        entityResult.EndedAt = new Date();
+                        if (result && result.length > 0) {
+                            if (bNewRecord) {
+                                let hydratedPk = false;
+                                for (const pkField of entity.EntityInfo.PrimaryKeys) {
+                                    const fieldObj = entity.Fields.find(f => f.Name === pkField.Name);
+                                    if (fieldObj && (fieldObj.Value === null || fieldObj.Value === undefined) && result[0][pkField.Name] != null) {
+                                        fieldObj.Value = result[0][pkField.Name];
+                                        hydratedPk = true;
+                                    }
+                                }
+                                if (hydratedPk) {
+                                    entity.PrimaryKey.LoadFromEntityFields(entity.PrimaryKeys);
+                                }
+                            }
+                            if (enlistInTx) {
+                                await this.OnDurableAfterSaveExecute(entity, user, options, saveContext);
+                            }
+                            if (saveTxScope) {
+                                await saveTxScope.Commit();
+                                saveTxCommitted = true;
+                            }
                         }
-                        return mergedRow;
+                        else {
+                            if (bNewRecord)
+                                throw new Error(`SQL Error: Error creating new record, no rows returned from SQL: ${sqlDetails.literalSQL ?? sqlDetails.fullSQL}`);
+                            else
+                                throw new Error(`SQL Error: Error updating record, no MATCHING rows found within the database: ${sqlDetails.literalSQL ?? sqlDetails.fullSQL}`);
+                        }
+                    }
+                    catch (innerErr) {
+                        if (saveTxScope && !saveTxCommitted) {
+                            await saveTxScope.Rollback();
+                        }
+                        throw innerErr;
+                    }
+                    this.OnAfterSaveExecute(entity, user, options, saveContext);
+                    entityResult.Success = true;
+                    // In 'datestamps_only' mode, the SP/query returned only the PK and
+                    // __mj_CreatedAt/__mj_UpdatedAt columns. Merge those returned values
+                    // onto the pre-save snapshot so caller-set fields remain intact without
+                    // falsely marking concurrent in-flight mutations as clean.
+                    let mergedRow;
+                    if (preSaveValues) {
+                        mergedRow = { ...preSaveValues, ...result[0] };
+                        Object.defineProperty(mergedRow, '__mj_preMerged', {
+                            value: true,
+                            enumerable: false,
+                            configurable: true,
+                        });
                     }
                     else {
-                        if (bNewRecord)
-                            throw new Error(`SQL Error: Error creating new record, no rows returned from SQL: ${sqlDetails.literalSQL ?? sqlDetails.fullSQL}`);
-                        else
-                            throw new Error(`SQL Error: Error updating record, no MATCHING rows found within the database: ${sqlDetails.literalSQL ?? sqlDetails.fullSQL}`);
+                        mergedRow = result[0];
+                    }
+                    // OnSaveCompleted may return patch fields (e.g., updated lat/lng
+                    // from geocoding) that need to be merged onto the SP result before
+                    // the entity loads the data via finalizeSave().
+                    const patches = await this.OnSaveCompleted(entity, sqlDetails, user, options, saveContext);
+                    if (patches) {
+                        Object.assign(mergedRow, patches);
                     }
+                    return mergedRow;
                 }
             }
             else {
@@ -1704,6 +1902,11 @@ export class DatabaseProviderBase extends ProviderBase {
             LogError(e);
             throw e;
         }
+        finally {
+            if (transactionPreprocessingRegistered && !transactionReadyRaised) {
+                entity.RaiseReadyForTransaction();
+            }
+        }
     }
     /**
      * Deletes an entity record — the full orchestration flow shared by all DB providers.
@@ -1717,8 +1920,11 @@ export class DatabaseProviderBase extends ProviderBase {
      */
     async Delete(entity, options, user) {
         const entityResult = new BaseEntityResult();
+        let transactionPreprocessingRegistered = false;
+        let transactionReadyRaised = false;
         try {
             entity.RegisterTransactionPreprocessing();
+            transactionPreprocessingRegistered = Boolean(entity.TransactionGroup);
             // External-data-source entities are read-only (see Save) — refuse deletes at the provider
             // layer regardless of the generated base class. The normal path (ReadOnlyExternalBaseEntity)
             // returns false before reaching here; this backstop intentionally throws only for the
@@ -1758,6 +1964,7 @@ export class DatabaseProviderBase extends ProviderBase {
             if (entity.TransactionGroup && !bReplay) {
                 // ---- Transaction Group path ----
                 entity.RaiseReadyForTransaction();
+                transactionReadyRaised = true;
                 const extraData = this.GetTransactionExtraData(entity);
                 if (entity.EntityInfo.TrackRecordChanges) {
                     Object.defineProperty(extraData, 'simpleSQLFallback', {
@@ -1774,7 +1981,8 @@ export class DatabaseProviderBase extends ProviderBase {
                         // (PostgreSQL accepts its legacy `_result_id` shape there).
                         if (!this.ValidateDeleteResult(entity, [transactionResult], entityResult)) {
                             entityResult.Success = false;
-                            return;
+                            throw new Error(entityResult.Message ||
+                                `Failed to delete ${entity.EntityInfo.Name}: record not found or primary key mismatch`);
                         }
                         this.OnAfterDeleteExecute(entity, user, options);
                         entityResult.NewValues = this.MapTransactionResultToNewValues(transactionResult);
@@ -1782,7 +1990,10 @@ export class DatabaseProviderBase extends ProviderBase {
                     }
                     else {
                         entityResult.Success = false;
-                        entityResult.Message = 'Transaction failed to commit';
+                        if (!entityResult.Message) {
+                            entityResult.Message =
+                                transactionResult instanceof Error ? transactionResult.message : 'Transaction failed to commit';
+                        }
                     }
                 }));
                 return true;
@@ -1821,6 +2032,11 @@ export class DatabaseProviderBase extends ProviderBase {
             entityResult.EndedAt = new Date();
             return false;
         }
+        finally {
+            if (transactionPreprocessingRegistered && !transactionReadyRaised) {
+                entity.RaiseReadyForTransaction();
+            }
+        }
     }
     /**************************************************************************/
     // END ---- Save/Delete Orchestration