@itwin/core-backend 5.2.0-dev.3 → 5.2.0-dev.31

package/lib/esm/BackendLoggerCategory.js.map

@@ -1 +1 @@
-{"version":3,"file":"BackendLoggerCategory.js","sourceRoot":"","sources":["../../src/BackendLoggerCategory.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAEH;;;;GAIG;AACH,MAAM,CAAN,IAAY,qBA+FX;AA/FD,WAAY,qBAAqB;IAC/B,+DAA+D;IAC/D,qEAA4C,CAAA;IAE5C;;OAEG;IACH,6DAAoC,CAAA;IAEpC;;OAEG;IACH,2FAAkE,CAAA;IAElE;;OAEG;IACH,2DAAkC,CAAA;IAElC;;;;OAIG;IACH,mDAA0B,CAAA;IAE1B;;OAEG;IACH,+DAAsC,CAAA;IAEtC;;OAEG;IACH,6EAAoD,CAAA;IAEpD;;;OAGG;IACH,2DAAkC,CAAA;IAElC;;OAEG;IACH,+DAAsC,CAAA;IAEtC;;OAEG;IACH,mFAA0D,CAAA;IAE1D;;OAEG;IACH,2EAAkD,CAAA;IAElD;;OAEG;IACH,6EAAoD,CAAA;IAEpD;;OAEG;IACH,mEAA0C,CAAA;IAE1C;;OAEG;IACH,yDAAgC,CAAA;IAEhC;;OAEG;IACH,yEAAgD,CAAA;IAChD;;OAEG;IACH,6DAAoC,CAAA;IAEpC;;;OAGG;IACH,6DAAoC,CAAA;IAEpC;;;OAGG;IACH,6EAAoD,CAAA;IAEpD,gBAAgB;IAChB,6DAAoC,CAAA;AACtC,CAAC,EA/FW,qBAAqB,KAArB,qBAAqB,QA+FhC","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module Logging\n */\n\n/** Logger categories used by this package\n * @note All logger categories in this package start with the `core-backend` prefix.\n * @see [Logger]($bentley)\n * @public\n */\nexport enum BackendLoggerCategory {\n  /** The logger category used by API related to authorization */\n  Authorization = \"core-backend.Authorization\",\n\n  /** The logger category used by the following classes:\n   * - [[CodeSpecs]]\n   */\n  CodeSpecs = \"core-backend.CodeSpecs\",\n\n  /** The logger category used by the following classes:\n   * - [[CustomViewState3dCreator]]\n   */\n  CustomViewState3dCreator = \"core-backend.CustomViewState3dCreator\",\n\n  /** The logger category used by the [[DevTools]] class and related classes.\n   * @internal\n   */\n  DevTools = \"core-backend.DevTools\",\n\n  /** The logger category used by the following classes:\n   * - [[ChangeSummaryManager]]\n   * - [[ECDb]]\n   * - [[ECSqlStatement]]\n   */\n  ECDb = \"core-backend.ECDb\",\n\n  /** The logger category used by the following classes:\n   * - [[Functional]]\n   */\n  Functional = \"core-backend.Functional\",\n\n  /** The logger category used by the following classes:\n   * - [[LinearReferencing]]\n   */\n  LinearReferencing = \"core-backend.LinearReferencing\",\n\n  /** The logger category used by the following classes:\n   * - BriefcaseManager\n   * - [[IModelDb]]\n   */\n  IModelDb = \"core-backend.IModelDb\",\n\n  /** The logger category used by the following classes:\n   * - [[IModelHost]]\n   */\n  IModelHost = \"core-backend.IModelHost\",\n\n  /** The logger category used by the following classes:\n   * - TileRequestMemoizer\n   */\n  IModelTileRequestRpc = \"core-backend.IModelTileRequestRpc\",\n\n  /** The logger category used by the following classes:\n   * - IModelTileRpcImpl (Tile Uploading)\n   */\n  IModelTileUpload = \"core-backend.IModelTileUpload\",\n\n  /** The logger category used by the following classes:\n   * - TileStorage (tile upload/download)\n   */\n  IModelTileStorage = \"core-backend.IModelTileStorage\",\n\n  /** The logger category used by the following classes:\n   * - [[Relationship]]\n   */\n  Relationship = \"core-backend.Relationship\",\n\n  /** The logger category used by the following classes:\n   * - [[Schemas]]\n   */\n  Schemas = \"core-backend.Schemas\",\n\n  /** The logger category used by the following classes:\n   * - [[PromiseMemoizer]]\n   */\n  PromiseMemoizer = \"core-backend.PromiseMemoizer\",\n  /** The logger category used by the following classes:\n   * - [[EventSink]]\n   */\n  EventSink = \"core-backend.EventSink\",\n\n  /** The logger category used by the following classes:\n   * - [[NativeHost]], [[NativeAppStorage]]\n   * @internal\n   */\n  NativeApp = \"core-backend.NativeApp\",\n\n  /** The logger category used by the following classes:\n   * - [[ViewStateHydrator]]\n   * @internal\n   */\n  ViewStateHydrator = \"core-backend.ViewStateHydrator\",\n\n  /** @internal */\n  Workspace = \"core-backend.Workspace\",\n}\n"]}
+{"version":3,"file":"BackendLoggerCategory.js","sourceRoot":"","sources":["../../src/BackendLoggerCategory.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AAEH;;;;GAIG;AACH,MAAM,CAAN,IAAY,qBAsGX;AAtGD,WAAY,qBAAqB;IAC/B,+DAA+D;IAC/D,qEAA4C,CAAA;IAE5C;;OAEG;IACH,6DAAoC,CAAA;IAEpC;;OAEG;IACH,2FAAkE,CAAA;IAElE;;OAEG;IACH,2DAAkC,CAAA;IAElC;;;;OAIG;IACH,mDAA0B,CAAA;IAE1B;;OAEG;IACH,+DAAsC,CAAA;IAEtC;;OAEG;IACH,6EAAoD,CAAA;IAEpD;;;OAGG;IACH,2DAAkC,CAAA;IAElC;;OAEG;IACH,+DAAsC,CAAA;IAEtC;;OAEG;IACH,mFAA0D,CAAA;IAE1D;;OAEG;IACH,2EAAkD,CAAA;IAElD;;OAEG;IACH,6EAAoD,CAAA;IAEpD;;OAEG;IACH,mEAA0C,CAAA;IAE1C;;OAEG;IACH,yDAAgC,CAAA;IAEhC;;OAEG;IACH,yEAAgD,CAAA;IAChD;;OAEG;IACH,6DAAoC,CAAA;IAEpC;;;;OAIG;IACH,mEAA0C,CAAA;IAE1C;;;OAGG;IACH,6DAAoC,CAAA;IAEpC;;;OAGG;IACH,6EAAoD,CAAA;IAEpD,gBAAgB;IAChB,6DAAoC,CAAA;AACtC,CAAC,EAtGW,qBAAqB,KAArB,qBAAqB,QAsGhC","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module Logging\n */\n\n/** Logger categories used by this package\n * @note All logger categories in this package start with the `core-backend` prefix.\n * @see [Logger]($bentley)\n * @public\n */\nexport enum BackendLoggerCategory {\n  /** The logger category used by API related to authorization */\n  Authorization = \"core-backend.Authorization\",\n\n  /** The logger category used by the following classes:\n   * - [[CodeSpecs]]\n   */\n  CodeSpecs = \"core-backend.CodeSpecs\",\n\n  /** The logger category used by the following classes:\n   * - [[CustomViewState3dCreator]]\n   */\n  CustomViewState3dCreator = \"core-backend.CustomViewState3dCreator\",\n\n  /** The logger category used by the [[DevTools]] class and related classes.\n   * @internal\n   */\n  DevTools = \"core-backend.DevTools\",\n\n  /** The logger category used by the following classes:\n   * - [[ChangeSummaryManager]]\n   * - [[ECDb]]\n   * - [[ECSqlStatement]]\n   */\n  ECDb = \"core-backend.ECDb\",\n\n  /** The logger category used by the following classes:\n   * - [[Functional]]\n   */\n  Functional = \"core-backend.Functional\",\n\n  /** The logger category used by the following classes:\n   * - [[LinearReferencing]]\n   */\n  LinearReferencing = \"core-backend.LinearReferencing\",\n\n  /** The logger category used by the following classes:\n   * - BriefcaseManager\n   * - [[IModelDb]]\n   */\n  IModelDb = \"core-backend.IModelDb\",\n\n  /** The logger category used by the following classes:\n   * - [[IModelHost]]\n   */\n  IModelHost = \"core-backend.IModelHost\",\n\n  /** The logger category used by the following classes:\n   * - TileRequestMemoizer\n   */\n  IModelTileRequestRpc = \"core-backend.IModelTileRequestRpc\",\n\n  /** The logger category used by the following classes:\n   * - IModelTileRpcImpl (Tile Uploading)\n   */\n  IModelTileUpload = \"core-backend.IModelTileUpload\",\n\n  /** The logger category used by the following classes:\n   * - TileStorage (tile upload/download)\n   */\n  IModelTileStorage = \"core-backend.IModelTileStorage\",\n\n  /** The logger category used by the following classes:\n   * - [[Relationship]]\n   */\n  Relationship = \"core-backend.Relationship\",\n\n  /** The logger category used by the following classes:\n   * - [[Schemas]]\n   */\n  Schemas = \"core-backend.Schemas\",\n\n  /** The logger category used by the following classes:\n   * - [[PromiseMemoizer]]\n   */\n  PromiseMemoizer = \"core-backend.PromiseMemoizer\",\n  /** The logger category used by the following classes:\n   * - [[EventSink]]\n   */\n  EventSink = \"core-backend.EventSink\",\n\n  /** The logger category used by the following classes:\n   * - [[StashManager]]\n   * - [[StashError]]\n   * @internal\n   */\n  StashManager = \"core-backend.StashManager\",\n\n  /** The logger category used by the following classes:\n   * - [[NativeHost]], [[NativeAppStorage]]\n   * @internal\n   */\n  NativeApp = \"core-backend.NativeApp\",\n\n  /** The logger category used by the following classes:\n   * - [[ViewStateHydrator]]\n   * @internal\n   */\n  ViewStateHydrator = \"core-backend.ViewStateHydrator\",\n\n  /** @internal */\n  Workspace = \"core-backend.Workspace\",\n}\n"]}

package/lib/esm/BriefcaseManager.d.ts

@@ -6,6 +6,7 @@ import { BriefcaseId, BriefcaseProps, ChangesetFileProps, ChangesetIndex, Change
 import { AcquireNewBriefcaseIdArg, DownloadChangesetArg, DownloadChangesetRangeArg, IModelNameArg } from "./BackendHubAccess";
 import { ProgressFunction } from "./CheckpointManager";
 import { BriefcaseDb, IModelDb, TokenArg } from "./IModelDb";
+import { StashProps } from "./StashManager";
 /** The argument for [[BriefcaseManager.downloadBriefcase]]
  * @public
 */
@@ -33,7 +34,8 @@ export interface PushChangesArgs extends TokenArg {
     /** The delay to wait between retry attempts on failed pushes. Default is 3 seconds. */
     pushRetryDelay?: BeDuration;
     /**
-     *  For testing purpose
+     *  (unused)
+     * @deprecated Not used by BriefcaseManager. Caller should remove this flag.
      * @internal
      */
     noFastForward?: true;
@@ -55,7 +57,8 @@ export type PullChangesArgs = ToChangesetArgs & {
      */
     onProgress?: ProgressFunction;
     /**
-     *  For testing purpose
+     *  (unused)
+     * @deprecated Not used by BriefcaseManager. Caller should remove this flag.
      * @internal
      */
     noFastForward?: true;
@@ -77,6 +80,8 @@ export type RevertChangesArgs = Optional<PushChangesArgs, "description"> & {
  * @public
  */
 export declare class BriefcaseManager {
+    /** @internal */
+    static readonly PULL_MERGE_RESTORE_POINT_NAME = "$pull_merge_restore_point";
     /** Get the local path of the folder storing files that are associated with an imodel */
     static getIModelPath(iModelId: GuidString): LocalDirName;
     /** @internal */
@@ -209,8 +214,57 @@ export declare class BriefcaseManager {
     private static applySingleChangeset;
     /** @internal */
     static revertTimelineChanges(db: IModelDb, arg: RevertChangesArgs): Promise<void>;
-    /** @internal */
+    /**
+     * @internal
+     * Pulls and applies changesets from the iModelHub to the specified IModelDb instance.
+     *
+     * This method downloads and applies all changesets required to bring the local briefcase up to the specified changeset index.
+     * It supports both forward and reverse application of changesets, depending on the `toIndex` argument.
+     * If there are pending local transactions and a reverse operation is requested, an error is thrown.
+     * The method manages restore points for safe merging, handles local transaction reversal, applies each changeset in order,
+     * and resumes or rebases local changes as appropriate for the type of database.
+     *
+     * @param db The IModelDb instance to which changesets will be applied. Must be open and writable.
+     * @param arg The arguments for pulling changesets, including access token, target changeset index, and optional progress callback.
+     * @throws IModelError If the briefcase is not open in read-write mode, if there are pending transactions when reversing, or if applying a changeset fails.
+     * @returns A promise that resolves when all required changesets have been applied.
+     */
     static pullAndApplyChangesets(db: IModelDb, arg: PullChangesArgs): Promise<void>;
+    /**
+     * @internal
+     * Creates a restore point for the specified briefcase database.
+     *
+     * @param db - The {@link BriefcaseDb} instance for which to create the restore point.
+     * @param name - The unique name for the restore point. Must be a non-empty string.
+     * @returns A promise that resolves to the created stash object representing the restore point.
+     */
+    static createRestorePoint(db: BriefcaseDb, name: string): Promise<StashProps>;
+    /**
+     * @internal
+     * Drops a previously created restore point from the specified briefcase database.
+     *
+     * @param db - The {@link BriefcaseDb} instance from which to drop the restore point.
+     * @param name - The name of the restore point to be dropped. Must be a non-empty string.
+     */
+    static dropRestorePoint(db: BriefcaseDb, name: string): void;
+    /**
+     * @internal
+     * Checks if a restore point with the specified name exists in the given briefcase database.
+     *
+     * @param db - The {@link BriefcaseDb} instance to search within.
+     * @param name - The name of the restore point to check for existence.
+     * @returns `true` if the restore point exists and its stash is present; otherwise, `false`.
+     */
+    static containsRestorePoint(db: BriefcaseDb, name: string): boolean;
+    private static makeRestorePointKey;
+    /**
+     * @internal
+     * Restores the state of a briefcase database to a previously saved restore point.
+     *
+     * @param db - The {@link BriefcaseDb} instance to restore.
+     * @param name - The name of the restore point to apply.
+     */
+    static restorePoint(db: BriefcaseDb, name: string): Promise<void>;
     /** create a changeset from the current changes, and push it to iModelHub */
     private static pushChanges;
     /** Pull/merge (if necessary), then push all local changes as a changeset. Called by [[BriefcaseDb.pushChanges]]

package/lib/esm/BriefcaseManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BriefcaseManager.d.ts","sourceRoot":"","sources":["../../src/BriefcaseManager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"BriefcaseManager.d.ts","sourceRoot":"","sources":["../../src/BriefcaseManager.ts"],"names":[],"mappings":"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"}

package/lib/esm/BriefcaseManager.js

@@ -6,22 +6,26 @@
  * @module iModels
  */
 // cspell:ignore cset csets ecchanges
-import * as path from "path";
+import * as path from "node:path";
+import * as os from "node:os";
 import { BeDuration, ChangeSetStatus, DbResult, IModelHubStatus, IModelStatus, Logger, OpenMode, StopWatch } from "@itwin/core-bentley";
 import { BriefcaseIdValue, ChangesetType, IModelError, IModelVersion, } from "@itwin/core-common";
 import { BackendLoggerCategory } from "./BackendLoggerCategory";
 import { CheckpointManager } from "./CheckpointManager";
-import { IModelDb } from "./IModelDb";
+import { BriefcaseDb, IModelDb } from "./IModelDb";
 import { IModelHost } from "./IModelHost";
 import { IModelJsFs } from "./IModelJsFs";
 import { SchemaSync } from "./SchemaSync";
 import { _hubAccess, _nativeDb, _releaseAllLocks } from "./internal/Symbols";
 import { IModelNative } from "./internal/NativePlatform";
+import { StashManager } from "./StashManager";
 const loggerCategory = BackendLoggerCategory.IModelDb;
 /** Manages downloading Briefcases and downloading and uploading changesets.
  * @public
  */
 export class BriefcaseManager {
+    /** @internal */
+    static PULL_MERGE_RESTORE_POINT_NAME = "$pull_merge_restore_point";
     /** Get the local path of the folder storing files that are associated with an imodel */
     static getIModelPath(iModelId) { return path.join(this._cacheDir, iModelId); }
     /** @internal */
@@ -135,7 +139,7 @@ export class BriefcaseManager {
      * @note *It is invalid to edit briefcases on a shared network drive* and that is a sure way to corrupt your briefcase (see https://www.sqlite.org/howtocorrupt.html)
      */
     static async downloadBriefcase(arg) {
-        const briefcaseId = arg.briefcaseId ?? await this.acquireNewBriefcaseId(arg);
+        const briefcaseId = arg.briefcaseId ?? await this.acquireNewBriefcaseId({ deviceName: `${os.hostname()}:${os.type()}:${os.arch()}`, ...arg });
         const fileName = arg.fileName ?? this.getFileName({ ...arg, briefcaseId });
         if (IModelJsFs.existsSync(fileName))
             throw new IModelError(IModelStatus.FileAlreadyExists, `Briefcase "${fileName}" already exists`);
@@ -238,7 +242,7 @@ export class BriefcaseManager {
                 IModelJsFs.unlinkSync(filePath);
         }
         catch (err) {
-            throw new IModelError(IModelStatus.BadRequest, `cannot delete briefcase file ${err}`);
+            throw new IModelError(IModelStatus.BadRequest, `cannot delete briefcase file ${String(err)}`);
         }
         // next, delete all files that start with the briefcase's filePath (e.g. "a.bim-locks", "a.bim-journal", etc.)
         try {
@@ -261,7 +265,7 @@ export class BriefcaseManager {
             IModelJsFs.unlinkSync(pathname);
         }
         catch (error) {
-            Logger.logError(loggerCategory, `Cannot delete file ${pathname}, ${error}`);
+            Logger.logError(loggerCategory, `Cannot delete file ${pathname}, ${String(error)}`);
             return false;
         }
         return true;
@@ -397,15 +401,30 @@ export class BriefcaseManager {
         });
         db.notifyChangesetApplied();
     }
-    /** @internal */
+    /**
+     * @internal
+     * Pulls and applies changesets from the iModelHub to the specified IModelDb instance.
+     *
+     * This method downloads and applies all changesets required to bring the local briefcase up to the specified changeset index.
+     * It supports both forward and reverse application of changesets, depending on the `toIndex` argument.
+     * If there are pending local transactions and a reverse operation is requested, an error is thrown.
+     * The method manages restore points for safe merging, handles local transaction reversal, applies each changeset in order,
+     * and resumes or rebases local changes as appropriate for the type of database.
+     *
+     * @param db The IModelDb instance to which changesets will be applied. Must be open and writable.
+     * @param arg The arguments for pulling changesets, including access token, target changeset index, and optional progress callback.
+     * @throws IModelError If the briefcase is not open in read-write mode, if there are pending transactions when reversing, or if applying a changeset fails.
+     * @returns A promise that resolves when all required changesets have been applied.
+     */
     static async pullAndApplyChangesets(db, arg) {
-        if (!db.isOpen || db[_nativeDb].isReadonly()) // don't use db.isReadonly - we reopen the file writable just for this operation but db.isReadonly is still true
+        const nativeDb = db[_nativeDb];
+        if (!db.isOpen || nativeDb.isReadonly()) // don't use db.isReadonly - we reopen the file writable just for this operation but db.isReadonly is still true
             throw new IModelError(ChangeSetStatus.ApplyError, "Briefcase must be open ReadWrite to process change sets");
         let currentIndex = db.changeset.index;
         if (currentIndex === undefined)
             currentIndex = (await IModelHost[_hubAccess].queryChangeset({ accessToken: arg.accessToken, iModelId: db.iModelId, changeset: { id: db.changeset.id } })).index;
         const reverse = (arg.toIndex && arg.toIndex < currentIndex) ? true : false;
-        if (db[_nativeDb].hasPendingTxns() && reverse) {
+        if (nativeDb.hasPendingTxns() && reverse) {
             throw new IModelError(ChangeSetStatus.ApplyError, "Cannot reverse changesets when there are pending changes");
         }
         // Download change sets
@@ -420,53 +439,139 @@ export class BriefcaseManager {
             return; // nothing to apply
         if (reverse)
             changesets.reverse();
-        let appliedChangesets = -1;
-        if (db[_nativeDb].hasPendingTxns() && !reverse && !arg.noFastForward) {
-            // attempt to perform fast forward
-            for (const changeset of changesets) {
-                // do not waste time on schema changesets. They cannot be fastforwarded.
-                if (changeset.changesType === ChangesetType.Schema || changeset.changesType === ChangesetType.SchemaSync)
-                    break;
-                try {
-                    const stopwatch = new StopWatch(`[${changeset.id}]`, true);
-                    Logger.logInfo(loggerCategory, `Starting application of changeset with id ${stopwatch.description} using fast forward method`);
-                    await this.applySingleChangeset(db, changeset, true);
-                    Logger.logInfo(loggerCategory, `Applied changeset with id ${stopwatch.description} (${stopwatch.elapsedSeconds} seconds)`);
-                    appliedChangesets++;
-                    db.saveChanges();
-                }
-                catch {
-                    db.abandonChanges();
-                    break;
+        const briefcaseDb = db instanceof BriefcaseDb ? db : undefined;
+        // create restore point if certain conditions are met
+        if (briefcaseDb && briefcaseDb.txns.hasPendingTxns && !briefcaseDb.txns.hasPendingSchemaChanges && !reverse && !IModelHost.configuration?.disableRestorePointOnPullMerge) {
+            Logger.logInfo(loggerCategory, `Creating restore point ${this.PULL_MERGE_RESTORE_POINT_NAME}`);
+            await this.createRestorePoint(briefcaseDb, this.PULL_MERGE_RESTORE_POINT_NAME);
+        }
+        if (!reverse) {
+            const reversedTxns = nativeDb.pullMergeReverseLocalChanges();
+            Logger.logInfo(loggerCategory, `Reversed ${reversedTxns.length} local changes`);
+        }
+        // apply incoming changes
+        for (const changeset of changesets) {
+            const stopwatch = new StopWatch(`[${changeset.id}]`, true);
+            Logger.logInfo(loggerCategory, `Starting application of changeset with id ${stopwatch.description}`);
+            try {
+                await this.applySingleChangeset(db, changeset, false);
+                Logger.logInfo(loggerCategory, `Applied changeset with id ${stopwatch.description} (${stopwatch.elapsedSeconds} seconds)`);
+            }
+            catch (err) {
+                if (err instanceof Error) {
+                    Logger.logError(loggerCategory, `Error applying changeset with id ${stopwatch.description}: ${err.message}`);
                 }
+                db.abandonChanges();
+                throw err;
             }
         }
-        if (appliedChangesets < changesets.length - 1) {
-            db[_nativeDb].pullMergeBegin();
-            for (const changeset of changesets.filter((_, index) => index > appliedChangesets)) {
-                const stopwatch = new StopWatch(`[${changeset.id}]`, true);
-                Logger.logInfo(loggerCategory, `Starting application of changeset with id ${stopwatch.description}`);
-                try {
-                    await this.applySingleChangeset(db, changeset, false);
-                    Logger.logInfo(loggerCategory, `Applied changeset with id ${stopwatch.description} (${stopwatch.elapsedSeconds} seconds)`);
+        if (!reverse) {
+            if (briefcaseDb) {
+                await briefcaseDb.txns.rebaser.resume();
+            }
+            else {
+                // Only Briefcase has change management. Following is
+                // for test related to standalone db with txn enabled.
+                nativeDb.pullMergeRebaseBegin();
+                let txnId = nativeDb.pullMergeRebaseNext();
+                while (txnId) {
+                    nativeDb.pullMergeRebaseReinstateTxn();
+                    nativeDb.pullMergeRebaseUpdateTxn();
+                    txnId = nativeDb.pullMergeRebaseNext();
                 }
-                catch (err) {
-                    if (err instanceof Error) {
-                        Logger.logError(loggerCategory, `Error applying changeset with id ${stopwatch.description}: ${err.message}`);
-                    }
-                    db.abandonChanges();
-                    db[_nativeDb].pullMergeEnd();
-                    throw err;
+                nativeDb.pullMergeRebaseEnd();
+                if (!nativeDb.isReadonly) {
+                    nativeDb.saveChanges("Merge.");
                 }
             }
-            db[_nativeDb].pullMergeEnd();
-            if (!db.isReadonly) {
-                db.saveChanges("Merge.");
+            if (briefcaseDb && this.containsRestorePoint(briefcaseDb, this.PULL_MERGE_RESTORE_POINT_NAME)) {
+                Logger.logInfo(loggerCategory, `Dropping restore point ${this.PULL_MERGE_RESTORE_POINT_NAME}`);
+                this.dropRestorePoint(briefcaseDb, this.PULL_MERGE_RESTORE_POINT_NAME);
             }
         }
         // notify listeners
         db.notifyChangesetApplied();
     }
+    /**
+     * @internal
+     * Creates a restore point for the specified briefcase database.
+     *
+     * @param db - The {@link BriefcaseDb} instance for which to create the restore point.
+     * @param name - The unique name for the restore point. Must be a non-empty string.
+     * @returns A promise that resolves to the created stash object representing the restore point.
+     */
+    static async createRestorePoint(db, name) {
+        Logger.logTrace(loggerCategory, `Creating restore point ${name}`);
+        this.dropRestorePoint(db, name);
+        const stash = await StashManager.stash({ db, description: this.makeRestorePointKey(name) });
+        db[_nativeDb].saveLocalValue(this.makeRestorePointKey(name), stash.id);
+        db.saveChanges("Create restore point");
+        Logger.logTrace(loggerCategory, `Created restore point ${name}`, () => stash);
+        return stash;
+    }
+    /**
+     * @internal
+     * Drops a previously created restore point from the specified briefcase database.
+     *
+     * @param db - The {@link BriefcaseDb} instance from which to drop the restore point.
+     * @param name - The name of the restore point to be dropped. Must be a non-empty string.
+     */
+    static dropRestorePoint(db, name) {
+        Logger.logTrace(loggerCategory, `Dropping restore point ${name}`);
+        const restorePointId = db[_nativeDb].queryLocalValue(this.makeRestorePointKey(name));
+        if (restorePointId) {
+            StashManager.dropStash({ db, stash: restorePointId });
+            db[_nativeDb].deleteLocalValue(this.makeRestorePointKey(name));
+            db.saveChanges("Drop restore point");
+            Logger.logTrace(loggerCategory, `Dropped restore point ${name}`);
+        }
+    }
+    /**
+     * @internal
+     * Checks if a restore point with the specified name exists in the given briefcase database.
+     *
+     * @param db - The {@link BriefcaseDb} instance to search within.
+     * @param name - The name of the restore point to check for existence.
+     * @returns `true` if the restore point exists and its stash is present; otherwise, `false`.
+     */
+    static containsRestorePoint(db, name) {
+        Logger.logTrace(loggerCategory, `Checking if restore point ${name} exists`);
+        const key = this.makeRestorePointKey(name);
+        const restorePointId = db[_nativeDb].queryLocalValue(key);
+        if (!restorePointId) {
+            return false;
+        }
+        const stash = StashManager.tryGetStash({ db, stash: restorePointId });
+        if (!stash) {
+            Logger.logTrace(loggerCategory, `Restore point ${name} does not exist. Deleting ${key}`);
+            db[_nativeDb].deleteLocalValue(key);
+            return false;
+        }
+        return true;
+    }
+    static makeRestorePointKey(name) {
+        if (name.length === 0) {
+            throw new Error("Invalid restore point name");
+        }
+        return `restore_point/${name}`;
+    }
+    /**
+     * @internal
+     * Restores the state of a briefcase database to a previously saved restore point.
+     *
+     * @param db - The {@link BriefcaseDb} instance to restore.
+     * @param name - The name of the restore point to apply.
+     */
+    static async restorePoint(db, name) {
+        Logger.logTrace(loggerCategory, `Restoring to restore point ${name}`);
+        const restorePointId = db[_nativeDb].queryLocalValue(this.makeRestorePointKey(name));
+        if (!restorePointId) {
+            throw new Error(`Restore point not found: ${name}`);
+        }
+        await StashManager.restore({ db, stash: restorePointId });
+        Logger.logTrace(loggerCategory, `Restored to restore point ${name}`);
+        this.dropRestorePoint(db, name);
+    }
     /** create a changeset from the current changes, and push it to iModelHub */
     static async pushChanges(db, arg) {
         const changesetProps = db[_nativeDb].startCreateChangeset();
@@ -523,7 +628,11 @@ export class BriefcaseManager {
                 await BriefcaseManager.pullAndApplyChangesets(db, arg);
                 if (!db.skipSyncSchemasOnPullAndPush)
                     await SchemaSync.pull(db);
-                return await BriefcaseManager.pushChanges(db, arg);
+                // pullAndApply rebase changes and might remove redundant changes in local briefcase
+                // this mean hasPendingTxns was true before but now after pullAndApply it might be false
+                if (!db[_nativeDb].hasPendingTxns())
+                    return;
+                await BriefcaseManager.pushChanges(db, arg);
             }
             catch (err) {
                 if (retryCount-- <= 0 || err.errorNumber !== IModelHubStatus.PullIsRequired)