@itwin/core-backend 5.9.0-dev.8 → 5.9.0-dev.9

package/lib/esm/TxnManager.js

@@ -1036,6 +1036,7 @@ export class TxnManager {
     /** Return the depth of the multi-Txn stack. Generally for diagnostic use only. */
     getMultiTxnOperationDepth() { return this._nativeDb.getMultiTxnOperationDepth(); }
     /** Reverse (undo) the most recent operation(s) to this IModelDb.
+     * @note Consider using [[reverseTxnsAsync]] instead.
      * @param numOperations the number of operations to reverse. If this is greater than 1, the entire set of operations will
      *  be reinstated together when/if ReinstateTxn is called.
      * @note If there are any outstanding uncommitted changes, they are reversed.
@@ -1048,27 +1049,189 @@ export class TxnManager {
             this._nativeDb.abandonChanges();
         return this._nativeDb.reverseTxns(numOperations);
     }
-    /** Reverse the most recent operation. */
-    reverseSingleTxn() { return this.reverseTxns(1); }
-    /** Reverse all changes back to the beginning of the session. */
-    reverseAll() { return this._nativeDb.reverseAll(); }
+    /** Reverse the most recent operation.
+     * @note Consider using [[reverseSingleTxnAsync]] instead.
+     */
+    reverseSingleTxn() {
+        return this.reverseTxns(1);
+    }
+    /** Reverse all changes back to the beginning of the session.
+     * @note Consider using [[reverseAllTxnsAsync]] instead.
+     */
+    reverseAll() {
+        return this._nativeDb.reverseAll();
+    }
     /** Reverse all changes back to a previously saved TxnId.
+     * @note Consider using [[reverseToTxnAsync]] instead.
      * @param txnId a TxnId obtained from a previous call to GetCurrentTxnId.
      * @returns Success if the transactions were reversed, error status otherwise.
      * @see  [[getCurrentTxnId]] [[cancelTo]]
      */
-    reverseTo(txnId) { return this._nativeDb.reverseTo(txnId); }
+    reverseTo(txnId) {
+        return this._nativeDb.reverseTo(txnId);
+    }
     /** Reverse and then cancel (make non-reinstatable) all changes back to a previous TxnId.
+     * @note Consider using [[cancelToTxnAsync]] instead.
      * @param txnId a TxnId obtained from a previous call to [[getCurrentTxnId]]
      * @returns Success if the transactions were reversed and cleared, error status otherwise.
      */
-    cancelTo(txnId) { return this._nativeDb.cancelTo(txnId); }
+    cancelTo(txnId) {
+        return this._nativeDb.cancelTo(txnId);
+    }
+    /** Reverse (undo) the most recent operation(s) to this IModelDb. By default, this method also
+     * abandons the locks that were acquired for those operations.
+     * @beta
+     * @note This method will also abandon locks associated with any later, reversed Txns, if they have not
+     * already been abandoned. For example, if a call to [[reverseTxns]] reverses Txn 2 without abandoning
+     * its locks, and then this method is called to reverse Txn 1, it will abandon the locks associated
+     * with _both_ Txn 1 and Txn 2.
+     * @note If you do not want to abandon any locks, set [ReverseTxnArgs.retainLocks]($common) to true.
+     * @note If there are any outstanding uncommitted changes, they are reversed.
+     * @note The term "operation" is used rather than Txn, since multiple Txns can be grouped together via [[beginMultiTxnOperation]]. So,
+     * even if numOperations is 1, multiple Txns may be reversed if they were grouped together when they were made.
+     * @note If numOperations is too large only the operations are reversible are reversed.
+     * @param numOperations the number of operations to reverse. If this is greater than 1, the entire set of operations will
+     *  be reinstated together when/if ReinstateTxn is called.
+     * @param args Optional arguments to control the behavior of the reverse operation, such as whether to retain locks.
+     * @returns A Promise that resolves to success if the transactions were reversed, or rejects with an IModelError otherwise.
+     */
+    async reverseTxnsAsync(numOperations, args) {
+        await this.withLockAbandonment(args, () => this._nativeDb.reverseTxns(numOperations));
+    }
+    /** Reverse (undo) the most recent operation to this IModelDb. By default, this method also
+     * abandons the locks that were acquired for that operation.
+     * @beta
+     * @note This method will also abandon locks associated with any later, reversed Txns, if they have not
+     * already been abandoned. For example, if a call to [[reverseTxns]] reverses Txn 2 without abandoning
+     * its locks, and then this method is called to reverse Txn 1, it will abandon the locks associated
+     * with _both_ Txn 1 and Txn 2.
+     * @note If there are any outstanding uncommitted changes, they are reversed.
+     * @note The term "operation" is used rather than Txn, since multiple Txns can be grouped together via [[beginMultiTxnOperation]]. So,
+     * even though this method reverses only one operation, multiple Txns may be reversed if they were grouped together when they were made.
+     * @note If there are no reversible operations, this method does nothing and returns Success.
+     * @param args Optional arguments to control the behavior of the reverse operation, such as whether to retain locks.
+     * @returns A Promise that resolves to success if the transactions were reversed, or rejects with an IModelError otherwise.
+     */
+    async reverseSingleTxnAsync(args) {
+        await this.reverseTxnsAsync(1, args);
+    }
+    /** Reverse (undo) all operations back to the beginning of the session. By default, this method also
+     * abandons the locks that were acquired for those operations.
+     * @beta
+     * @note This method will also abandon locks associated with any later, reversed Txns, if they have not
+     * already been abandoned. For example, if a call to [[reverseTxns]] reverses Txn 2 without abandoning
+     * its locks, and then this method is called to reverse Txn 1, it will abandon the locks associated
+     * with _both_ Txn 1 and Txn 2.
+     * @note If there are any outstanding uncommitted changes, they are reversed.
+     * @note If there are no reversible operations, this method does nothing and returns Success.
+     * @param args Optional arguments to control the behavior of the reverse operation, such as whether to retain locks.
+     * @returns A Promise that resolves to success if the transactions were reversed, or rejects with an IModelError otherwise.
+     */
+    async reverseAllTxnsAsync(args) {
+        await this.withLockAbandonment(args, () => this._nativeDb.reverseAll());
+    }
+    /** Reverse (undo) all operations back to a previously saved TxnId. By default, this method also
+     * abandons the locks that were acquired for those operations.
+     * @beta
+     * @note This method will also abandon locks associated with any later, reversed Txns, if they have not
+     * already been abandoned. For example, if a call to [[reverseTxns]] reverses Txn 2 without abandoning
+     * its locks, and then this method is called to reverse Txn 1, it will abandon the locks associated
+     * with _both_ Txn 1 and Txn 2.
+     * @note If there are any outstanding uncommitted changes, they are reversed.
+     * @param txnId a TxnId obtained from a previous call to GetCurrentTxnId.
+     * @param args Optional arguments to control the behavior of the reverse operation, such as whether to abandon locks.
+     * @returns A Promise that resolves to success if the transactions were reversed, or rejects with an IModelError otherwise.
+     * @see  [[getCurrentTxnId]] [[cancelTo]]
+     */
+    async reverseToTxnAsync(txnId, args) {
+        await this.withLockAbandonment(args, () => this._nativeDb.reverseTo(txnId));
+    }
+    /** Reverse and then cancel (make non-reinstatable) all operations back to a previous TxnId. By default, this
+     * method also abandons the locks that were acquired for those operations.
+     * @beta
+     * @note This method will also abandon locks associated with any later, reversed Txns, if they have not
+     * already been abandoned. For example, if a call to [[reverseTxns]] reverses Txn 2 without abandoning
+     * its locks, and then this method is called to reverse Txn 1, it will abandon the locks associated
+     * with _both_ Txn 1 and Txn 2.
+     * @note If there are any outstanding uncommitted changes, they are reversed.
+     * @param txnId a TxnId obtained from a previous call to [[getCurrentTxnId]]
+     * @param args Optional arguments to control the behavior of the reverse operation, such as whether to abandon locks.
+     * @returns A promise that resolves to success if the transactions were reversed and cleared, or rejects with an IModelError otherwise.
+     */
+    async cancelToTxnAsync(txnId, args) {
+        // First reverse and abandon locks. Only cancel if that succeeds.
+        // This is important because the locks would become unabandonable if we canceled first and
+        // _then_ the abandonment failed. We expect the call to cancelTo to return "NothingToUndo",
+        // but that's ok - it will still clear the already-reversed txns.
+        await this.withLockAbandonment(args, () => this._nativeDb.reverseTo(txnId));
+        const status = this._nativeDb.cancelTo(txnId);
+        if (status !== IModelStatus.Success && status !== IModelStatus.NothingToUndo)
+            throw new IModelError(status, IModelError.getErrorKey(status));
+        this._iModel.locks.clearTxnLockRecords(txnId);
+    }
+    async withLockAbandonment(args, doReverseCallback) {
+        const result = doReverseCallback();
+        if (result === IModelStatus.Success) {
+            if (!args?.retainLocks) {
+                // Abandon locks for the earliest txn, which abandons locks for the later ones, too.
+                await this._iModel.locks.abandonLocksForReversedTxn(this.getCurrentTxnId());
+            }
+        }
+        else {
+            throw new IModelError(result, IModelError.getErrorKey(result));
+        }
+    }
     /** Reinstate the most recently reversed transaction. Since at any time multiple transactions can be reversed, it
      * may take multiple calls to this method to reinstate all reversed operations.
      * @returns Success if a reversed transaction was reinstated, error status otherwise.
      * @note If there are any outstanding uncommitted changes, they are canceled before the Txn is reinstated.
+     * @note This method will return [[IModelStatus.LockNotHeld]] and will not reinstate the Txn if the locks
+     * originally acquired by the Txn have been abandoned. Use [[reinstateTxnAsync]] to re-acquire the locks
+     * and reinstate the Txn in a single operation.
+     */
+    reinstateTxn() {
+        // Verify that the locks required by this txn have not been abandoned.
+        // If so, this method has no way to re-acquire them because it is synchronous. This
+        // is basically a developer error, mixing reverseTxnAsync with reinstateTxn (non-Async).
+        const reinstateRange = this._nativeDb.getNextReinstateTxnRange();
+        if (this.isTxnIdValid(reinstateRange.firstTxnId) &&
+            !this._iModel.locks.holdsNecessaryLocksForReinstatingTxn(this.queryPreviousTxnId(reinstateRange.lastTxnId))) {
+            return IModelStatus.LockNotHeld;
+        }
+        return this._iModel.reinstateTxn();
+    }
+    /** Reinstate the most recently reversed transaction. This method will first attempt
+     * to re-acquire the required locks, if they were abandoned after the operation was reversed.
+     * Since at any time multiple transactions can be reversed, it may take multiple calls to this
+     * method to reinstate all reversed operations.
+     * @beta
+     * @note If there are any outstanding unsaved changes, they are canceled before the Txn is reinstated. Unless
+     * [ReinstateTxnArgs.retainLocks]($common) is true, the locks associated with the unsaved changes are also abandoned.
+     * @param args Optional arguments to control the behavior of the reinstate operation, such as whether to retain
+     * locks when abandoning unsaved changes.
+     * @returns A Promise that resolves to success if a reversed transaction was reinstated, or rejects with an IModelError otherwise.
      */
-    reinstateTxn() { return this._iModel.reinstateTxn(); }
+    async reinstateTxnAsync(args) {
+        // We must abandon any unsaved changes here because it will be too late
+        // when reinstateTxn does it.
+        if (this.hasUnsavedChanges) {
+            this._iModel.clearCaches({ instanceCachesOnly: true });
+            this._iModel[_nativeDb].abandonChanges();
+        }
+        if (!args?.retainLocks) {
+            await this._iModel.locks.abandonLocksForCurrentUnsavedTxn();
+        }
+        const reinstateRange = this._nativeDb.getNextReinstateTxnRange();
+        if (!this.isTxnIdValid(reinstateRange.firstTxnId)) {
+            throw new IModelError(IModelStatus.NothingToRedo, IModelError.getErrorKey(IModelStatus.NothingToRedo));
+        }
+        // Reacquire locks for the latest txn in the range, which will reacquire locks for all earlier txns, too.
+        await this._iModel.locks.acquireLocksForReinstatingTxn(this.queryPreviousTxnId(reinstateRange.lastTxnId));
+        const status = this.reinstateTxn();
+        if (status !== IModelStatus.Success) {
+            throw new IModelError(status, IModelError.getErrorKey(status));
+        }
+    }
     /** Get the Id of the first transaction, if any.
      */
     queryFirstTxnId() { return this._nativeDb.queryFirstTxnId(); }
@@ -1109,7 +1272,7 @@ export class TxnManager {
     get hasLocalChanges() { return this.hasUnsavedChanges || this.hasPendingTxns; }
     /** Destroy the record of all local changes that have yet to be saved and/or pushed.
      * This permanently eradicates your changes - use with caution!
-     * Typically, callers will want to subsequently use [[LockControl.releaseAllLocks]].
+     * Typically, callers will want to subsequently use [[LockControl.abandonAllLocks]].
      * After calling this function, [[hasLocalChanges]], [[hasPendingTxns]], and [[hasUnsavedChanges]] will all be `false`.
      */
     deleteAllTxns() {