@itwin/core-backend 5.2.0-dev.8 → 5.3.0-dev.1

package/lib/cjs/TxnManager.js

@@ -7,7 +7,7 @@
  * @module iModels
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TxnManager = exports.ChangeMergeManager = void 0;
+exports.TxnManager = exports.RebaseManager = void 0;
 exports.setMaxEntitiesPerEvent = setMaxEntitiesPerEvent;
 const touch = require("touch");
 const core_bentley_1 = require("@itwin/core-bentley");
@@ -16,6 +16,7 @@ const BackendLoggerCategory_1 = require("./BackendLoggerCategory");
 const IpcHost_1 = require("./IpcHost");
 const Symbols_1 = require("./internal/Symbols");
 const ChangesetConflictArgs_1 = require("./internal/ChangesetConflictArgs");
+const BriefcaseManager_1 = require("./BriefcaseManager");
 /** Strictly for tests. @internal */
 function setMaxEntitiesPerEvent(max) {
     const prevMax = ChangedEntitiesProc.maxPerEvent;
@@ -197,21 +198,162 @@ class ChangedEntitiesProc {
     }
 }
 /**
- * @internal
- * Manages conflict resolution during a merge operation.
-*/
-class ChangeMergeManager {
+ * Manages the process of merging and rebasing local changes (transactions) in a [[BriefcaseDb]] or [[StandaloneDb]].
+ *
+ * The `RebaseManager` coordinates the rebase of local transactions when pulling and merging changes from other sources,
+ * such as remote repositories or other users. It provides mechanisms to handle transaction conflicts, register custom conflict
+ * handlers, and manage the rebase workflow. This includes resuming rebases, invoking user-defined handlers for conflict resolution,
+ * and tracking the current merge/rebase state.
+ *
+ * Key responsibilities:
+ * - Orchestrates the rebase of local transactions after a pull/merge operation.
+ * - Allows registration and removal of custom conflict handlers to resolve changeset conflicts during rebase.
+ * - Provides methods to check the current merge/rebase state.
+ * - Raises events before and after each transaction is rebased.
+ * - Ensures changes are saved or aborted appropriately based on the outcome of the rebase process.
+ *
+ * @alpha
+ */
+class RebaseManager {
     _iModel;
     _conflictHandlers;
+    _customHandler;
     constructor(_iModel) {
         this._iModel = _iModel;
     }
-    resume() {
-        this._iModel[Symbols_1._nativeDb].pullMergeResume();
+    /**
+     * Resumes the rebase process for the current iModel, applying any pending local changes
+     * on top of the latest pulled changes from the remote source.
+     *
+     * This method performs the following steps:
+     * 1. Begins the rebase process using the native database.
+     * 2. Iterates through each transaction that needs to be rebased:
+     *    - Retrieves transaction properties.
+     *    - Raises events before and after rebasing each transaction.
+     *    - Optionally reinstates local changes based on the rebase handler.
+     *    - Optionally recomputes transaction data using the rebase handler.
+     *    - Updates the transaction in the native database.
+     * 3. Ends the rebase process and saves changes if the database is not read-only.
+     * 4. Drops any restore point associated with the pull-merge operation.
+     *
+     * If an error occurs during the process, the rebase is aborted and the error is rethrown.
+     *
+     * @throws {Error} If a transaction cannot be found or if any step in the rebase process fails.
+     */
+    async resume() {
+        const nativeDb = this._iModel[Symbols_1._nativeDb];
+        const txns = this._iModel.txns;
+        try {
+            nativeDb.pullMergeRebaseBegin();
+            let txnId = nativeDb.pullMergeRebaseNext();
+            while (txnId) {
+                const txnProps = txns.getTxnProps(txnId);
+                if (!txnProps) {
+                    throw new Error(`Transaction ${txnId} not found`);
+                }
+                txns.onRebaseTxnBegin.raiseEvent(txnProps);
+                core_bentley_1.Logger.logInfo(BackendLoggerCategory_1.BackendLoggerCategory.IModelDb, `Rebasing local changes for transaction ${txnId}`);
+                const shouldReinstate = this._customHandler?.shouldReinstate(txnProps) ?? true;
+                if (shouldReinstate) {
+                    nativeDb.pullMergeRebaseReinstateTxn();
+                    core_bentley_1.Logger.logInfo(BackendLoggerCategory_1.BackendLoggerCategory.IModelDb, `Reinstated local changes for transaction ${txnId}`);
+                }
+                if (this._customHandler) {
+                    await this._customHandler.recompute(txnProps);
+                }
+                nativeDb.pullMergeRebaseUpdateTxn();
+                txns.onRebaseTxnEnd.raiseEvent(txnProps);
+                txnId = nativeDb.pullMergeRebaseNext();
+            }
+            nativeDb.pullMergeRebaseEnd();
+            if (!nativeDb.isReadonly) {
+                nativeDb.saveChanges("Merge.");
+            }
+            if (BriefcaseManager_1.BriefcaseManager.containsRestorePoint(this._iModel, BriefcaseManager_1.BriefcaseManager.PULL_MERGE_RESTORE_POINT_NAME)) {
+                BriefcaseManager_1.BriefcaseManager.dropRestorePoint(this._iModel, BriefcaseManager_1.BriefcaseManager.PULL_MERGE_RESTORE_POINT_NAME);
+            }
+        }
+        catch (err) {
+            nativeDb.pullMergeRebaseAbortTxn();
+            throw err;
+        }
+    }
+    /**
+     * Determines whether the current transaction can be aborted.
+     *
+     * This method checks if a transaction is currently in progress and if a specific restore point,
+     * identified by `BriefcaseManager.PULL_MERGE_RESTORE_POINT_NAME`, exists in the briefcase manager.
+     *
+     * @returns {boolean} Returns `true` if a transaction is in progress and the required restore point exists; otherwise, returns `false`.
+     */
+    canAbort() {
+        return this.inProgress() && BriefcaseManager_1.BriefcaseManager.containsRestorePoint(this._iModel, BriefcaseManager_1.BriefcaseManager.PULL_MERGE_RESTORE_POINT_NAME);
+    }
+    /**
+     * Aborts the current transaction by restoring the iModel to a predefined restore point.
+     *
+     * If a restore point is available (as determined by `canAbort()`), this method restores the iModel
+     * to the state saved at the restore point named by `BriefcaseManager.PULL_MERGE_RESTORE_POINT_NAME`.
+     * If no restore point is available, an error is thrown.
+     *
+     * @returns A promise that resolves when the restore operation is complete.
+     * @throws {Error} If there is no restore point to abort to.
+     */
+    async abort() {
+        if (this.canAbort()) {
+            return BriefcaseManager_1.BriefcaseManager.restorePoint(this._iModel, BriefcaseManager_1.BriefcaseManager.PULL_MERGE_RESTORE_POINT_NAME);
+        }
+        else {
+            throw new Error("No restore point to abort to");
+        }
+    }
+    /**
+     * Sets the handler to be invoked for rebase operations.
+     *
+     * @param handler - The {@link RebaseHandler} to handle rebase events.
+     */
+    setCustomHandler(handler) {
+        if (this._customHandler) {
+            core_bentley_1.Logger.logWarning(BackendLoggerCategory_1.BackendLoggerCategory.IModelDb, "Rebase handler already set");
+        }
+        this._customHandler = handler;
     }
+    /**
+     * Determines whether a transaction is currently in progress.
+     *
+     * @returns {boolean} Returns `true` if there is an active transaction stage, otherwise `false`.
+     */
     inProgress() {
-        return this._iModel[Symbols_1._nativeDb].pullMergeInProgress();
+        return this._iModel[Symbols_1._nativeDb].pullMergeGetStage() !== "None";
     }
+    /**
+     * Indicates whether the current transaction manager is in the "Rebasing" stage.
+     *
+     * This property checks the internal native database's merge stage to determine if a rebase operation is in progress.
+     *
+     * @returns `true` if the transaction manager is currently rebasing; otherwise, `false`.
+     */
+    get isRebasing() {
+        return this._iModel[Symbols_1._nativeDb].pullMergeGetStage() === "Rebasing";
+    }
+    /**
+     * Indicates whether the current iModel is in the process of merging changes from a pull operation.
+     *
+     * @returns `true` if the iModel is currently merging changes; otherwise, `false`.
+     */
+    get isMerging() {
+        return this._iModel[Symbols_1._nativeDb].pullMergeGetStage() === "Merging";
+    }
+    /**
+     * Attempts to resolve a changeset conflict by invoking registered conflict handlers in sequence.
+     *
+     * Iterates through the linked list of conflict handlers, passing the provided conflict arguments to each handler.
+     * If a handler returns a defined resolution, logs the resolution and returns it immediately.
+     * If no handler resolves the conflict, returns `undefined`.
+     *
+     * @param args - The arguments describing the changeset conflict to resolve.
+     * @returns The conflict resolution provided by a handler, or `undefined` if no handler resolves the conflict.
+     */
     onConflict(args) {
         let curr = this._conflictHandlers;
         while (curr) {
@@ -224,6 +366,18 @@ class ChangeMergeManager {
         }
         return undefined;
     }
+    /**
+     * Registers a new conflict handler for rebase changeset conflicts.
+     *
+     * @param args - An object containing:
+     *   - `id`: A unique identifier for the conflict handler.
+     *   - `handler`: A function that handles rebase changeset conflicts and returns a `DbConflictResolution` or `undefined`.
+     * @throws IModelError if a conflict handler with the same `id` already exists.
+     *
+     * @remarks
+     * Conflict handlers are used during changeset rebase operations to resolve conflicts.
+     * Each handler must have a unique `id`. Attempting to register a handler with a duplicate `id` will result in an error.
+     */
     addConflictHandler(args) {
         const idExists = (id) => {
             let curr = this._conflictHandlers;
@@ -238,6 +392,14 @@ class ChangeMergeManager {
             throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, `Conflict handler with id ${args.id} already exists`);
         this._conflictHandlers = { ...args, next: this._conflictHandlers };
     }
+    /**
+     * Removes a conflict handler from the internal linked list by its identifier.
+     *
+     * @param id - The unique identifier of the conflict handler to remove.
+     *
+     * If the handler with the specified `id` exists in the list, it will be removed.
+     * If no handler with the given `id` is found, the method does nothing.
+     */
     removeConflictHandler(id) {
         if (!this._conflictHandlers)
             return;
@@ -257,7 +419,7 @@ class ChangeMergeManager {
         }
     }
 }
-exports.ChangeMergeManager = ChangeMergeManager;
+exports.RebaseManager = RebaseManager;
 /** Manages local changes to a [[BriefcaseDb]] or [[StandaloneDb]] via [Txns]($docs/learning/InteractiveEditing.md)
  * @public @preview
  */
@@ -270,11 +432,11 @@ class TxnManager {
         return this._isDisposed;
     }
     /** @internal */
-    changeMergeManager;
+    rebaser;
     /** @internal */
     constructor(_iModel) {
         this._iModel = _iModel;
-        this.changeMergeManager = new ChangeMergeManager(_iModel);
+        this.rebaser = new RebaseManager(_iModel);
         _iModel.onBeforeClose.addOnce(() => {
             this._isDisposed = true;
         });
@@ -372,12 +534,6 @@ class TxnManager {
         this.onAfterUndoRedo.raiseEvent(isUndo);
         IpcHost_1.IpcHost.notifyTxns(this._iModel, "notifyAfterUndoRedo", isUndo);
     }
-    _onRebaseTxnBegin(txn) {
-        this.onRebaseTxnBegin.raiseEvent(txn);
-    }
-    _onRebaseTxnEnd(txn) {
-        this.onRebaseTxnEnd.raiseEvent(txn);
-    }
     _onRebaseLocalTxnConflict(internalArg) {
         const args = new ChangesetConflictArgs_1.RebaseChangesetConflictArgs(internalArg, this._iModel);
         const getChangeMetaData = () => {
@@ -409,7 +565,7 @@ class TxnManager {
             }
         }
         try {
-            const resolution = this.changeMergeManager.onConflict(args);
+            const resolution = this.rebaser.onConflict(args);
             if (resolution !== undefined)
                 return resolution;
         }
@@ -440,11 +596,43 @@ class TxnManager {
             return core_bentley_1.DbConflictResolution.Skip;
         }
         if (args.cause === "Constraint") {
-            core_bentley_1.Logger.logInfo(BackendLoggerCategory_1.BackendLoggerCategory.IModelDb, "Constraint voilation detected. Generally caused by db constraints like UNIQUE index. Skipping local change.", getChangeMetaData());
+            core_bentley_1.Logger.logInfo(BackendLoggerCategory_1.BackendLoggerCategory.IModelDb, "Constraint violation detected. Generally caused by db constraints like UNIQUE index. Skipping local change.", getChangeMetaData());
             return core_bentley_1.DbConflictResolution.Skip;
         }
         return core_bentley_1.DbConflictResolution.Replace;
     }
+    /**
+     * @alpha
+     * Retrieves the txn properties for a given txn ID.
+     *
+     * @param id - The unique identifier of the transaction.
+     * @returns The properties of the transaction if found; otherwise, `undefined`.
+     */
+    getTxnProps(id) {
+        return this._iModel[Symbols_1._nativeDb].getTxnProps(id);
+    }
+    /**
+     * @alpha
+     * Iterates over all transactions in the sequence, yielding each transaction's properties.
+     *
+     * @yields {TxnProps} The properties of each transaction in the sequence.
+     */
+    *queryTxns() {
+        let txn = this.getTxnProps(this.queryFirstTxnId());
+        while (txn) {
+            yield txn;
+            txn = txn.nextId ? this.getTxnProps(txn.nextId) : undefined;
+        }
+    }
+    /**
+     * @alpha
+     * Retrieves the properties of the last saved txn via `IModelDb.saveChanges()`, if available.
+     *
+     * @returns The properties of the last saved txn, or `undefined` if none exist.
+     */
+    getLastSavedTxnProps() {
+        return this.getTxnProps(this.queryPreviousTxnId(this.getCurrentTxnId()));
+    }
     /** Dependency handlers may call method this to report a validation error.
      * @param error The error. If error.fatal === true, the transaction will cancel rather than commit.
      */
@@ -494,12 +682,18 @@ class TxnManager {
      * @see [[onReplayExternalTxns]] for the event raised before the changes are applied.
      */
     onReplayedExternalTxns = new core_bentley_1.BeEvent();
-    /** @internal */
+    /**
+     * @alpha
+     * Event raised when a rebase transaction begins.
+     */
     onRebaseTxnBegin = new core_bentley_1.BeEvent();
-    /** @internal */
+    /**
+     * @alpha
+     * Event raised when a rebase transaction ends.
+     */
     onRebaseTxnEnd = new core_bentley_1.BeEvent();
     /**
-     * if handler is set and it does not return undefiend then default handler will not be called
+     * if handler is set and it does not return undefined then default handler will not be called
      * @internal
      * */
     appCustomConflictHandler;
@@ -514,7 +708,7 @@ class TxnManager {
         this._nativeDb.restartTxnSession();
     }
     /** Determine whether current txn is propagating indirect changes or not. */
-    get isIndirectChanges() { return this._nativeDb.isIndirectChanges(); }
+    get isIndirectChanges() { return this.getMode() === "indirect"; }
     /** Determine if there are currently any reversible (undoable) changes from this editing session. */
     get isUndoPossible() { return this._nativeDb.isUndoPossible(); }
     /** Determine if there are currently any reinstatable (redoable) changes */
@@ -579,6 +773,11 @@ class TxnManager {
     queryPreviousTxnId(txnId) { return this._nativeDb.queryPreviousTxnId(txnId); }
     /** Get the Id of the current (tip) transaction.  */
     getCurrentTxnId() { return this._nativeDb.getCurrentTxnId(); }
+    /**
+     * @alpha
+     * Get the Id of the current session.
+     */
+    getCurrentSessionId() { return this._nativeDb.currentTxnSessionId(); }
     /** Get the description that was supplied when the specified transaction was saved. */
     getTxnDescription(txnId) { return this._nativeDb.getTxnDescription(txnId); }
     /** Test if a TxnId is valid */
@@ -592,6 +791,11 @@ class TxnManager {
      * @see [[IModelDb.saveChanges]]
      */
     get hasUnsavedChanges() { return this._nativeDb.hasUnsavedChanges(); }
+    /**
+     * @alpha
+     * Query if there are any pending schema changes in this IModelDb.
+     */
+    get hasPendingSchemaChanges() { return this._nativeDb.hasPendingSchemaChanges(); }
     /**
      * Query if there are changes in memory that have not been saved to the iModelDb or if there are Txns that are waiting to be pushed.
      * @see [[IModelDb.saveChanges]]
@@ -621,6 +825,28 @@ class TxnManager {
     getChangeTrackingMemoryUsed() {
         return this._iModel[Symbols_1._nativeDb].getChangeTrackingMemoryUsed();
     }
+    /**
+     * @alpha
+     * Get the current transaction mode.
+     * @returns The current transaction mode, either "direct" or "indirect".
+     */
+    getMode() {
+        return this._nativeDb.getTxnMode();
+    }
+    /**
+     * @alpha
+     * Execute a series of changes in an indirect transaction.
+     * @param callback The function containing the changes to make.
+     */
+    withIndirectTxnMode(callback) {
+        this._nativeDb.setTxnMode("indirect");
+        try {
+            callback();
+        }
+        finally {
+            this._nativeDb.setTxnMode("direct");
+        }
+    }
 }
 exports.TxnManager = TxnManager;
 //# sourceMappingURL=TxnManager.js.map