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

package/lib/esm/StashManager.js

@@ -0,0 +1,301 @@
+import { DbResult, Logger, OpenMode } from "@itwin/core-bentley";
+import { LockState } from "@itwin/core-common";
+import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import * as path from "node:path";
+import { BriefcaseManager } from "./BriefcaseManager";
+import { _elementWasCreated, _hubAccess, _nativeDb, _resetIModelDb } from "./internal/Symbols";
+import { SQLiteDb } from "./SQLiteDb";
+import { IModelHost } from "./IModelHost";
+import { BackendLoggerCategory } from "./BackendLoggerCategory";
+const loggerCategory = BackendLoggerCategory.StashManager;
+/**
+ * Custom error class for stash-related errors.
+ * @internal
+ */
+export class StashError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "StashError";
+        Logger.logError(loggerCategory, message);
+    }
+}
+var LockOrigin;
+(function (LockOrigin) {
+    LockOrigin[LockOrigin["Acquired"] = 0] = "Acquired";
+    LockOrigin[LockOrigin["NewElement"] = 1] = "NewElement";
+    LockOrigin[LockOrigin["Discovered"] = 2] = "Discovered";
+})(LockOrigin || (LockOrigin = {}));
+;
+/**
+ * Stash manager allow stash, drop, apply and merge stashes
+ * @internal
+ */
+export class StashManager {
+    static STASHES_ROOT_DIR_NAME = ".stashes";
+    /**
+     * Retrieves the root folder path for stash files associated with the specified BriefcaseDb.
+     *
+     * @param db - The BriefcaseDb instance for which to determine the stash root folder.
+     * @param ensureExists - If true, the stash root directory will be created if it does not already exist.
+     * @returns The absolute path to the stash root directory.
+     */
+    static getStashRootFolder(db, ensureExists) {
+        if (!db.isOpen || db.isReadonly)
+            throw new StashError("Database is not open or is readonly");
+        if (!existsSync(db[_nativeDb].getFilePath())) {
+            throw new StashError("Could not determine briefcase path");
+        }
+        const stashDir = path.join(path.dirname(db[_nativeDb].getFilePath()), this.STASHES_ROOT_DIR_NAME, `${db.briefcaseId}`);
+        if (ensureExists && !existsSync(stashDir)) {
+            mkdirSync(stashDir, { recursive: true });
+        }
+        return stashDir;
+    }
+    /**
+     * Retrieves the stash ID from the provided arguments.
+     *
+     * If the `stash` property of `args` is a string, it returns the string in lowercase.
+     * If the `stash` property is an object, it returns the `id` property of the object in lowercase.
+     *
+     * @param args - The arguments containing the stash information, which can be either a string or an object with an `id` property.
+     * @returns The stash ID as a lowercase string.
+     */
+    static getStashId(args) {
+        return (typeof args.stash === "string" ? args.stash : args.stash.id).toLowerCase();
+    }
+    /**
+     * Retrieves the file path to the stash file associated with the provided arguments.
+     *
+     * @param args - The arguments required to identify the stash, including the database reference.
+     * @returns The absolute path to the stash file.
+     */
+    static getStashFilePath(args) {
+        const stashRoot = this.getStashRootFolder(args.db, false);
+        if (!existsSync(stashRoot)) {
+            throw new StashError("Invalid stash");
+        }
+        const stashFilePath = path.join(stashRoot, `${this.getStashId(args)}.stash`);
+        if (!existsSync(stashFilePath)) {
+            throw new StashError("Invalid stash");
+        }
+        return stashFilePath;
+    }
+    /**
+     * Queries the stash database for lock IDs matching the specified state and origin.
+     *
+     * @param args - The arguments required to access the stash database.
+     * @param state - The lock state to filter by.
+     * @param origin - The lock origin to filter by.
+     * @returns An array of lock IDs (`Id64Array`) that match the given state and origin.
+     */
+    static queryLocks(args, state, origin) {
+        return this.withStash(args, (stashDb) => {
+            const query = `SELECT JSON_GROUP_ARRAY(FORMAT('0x%x', Id)) FROM [locks] WHERE State = ${state} AND origin = ${origin}`;
+            return stashDb.withPreparedSqliteStatement(query, (stmt) => {
+                if (stmt.step() === DbResult.BE_SQLITE_ROW) {
+                    return JSON.parse(stmt.getValueString(0));
+                }
+                return [];
+            });
+        });
+    }
+    /**
+     * Acquire locks for the specified stash. If this fail then stash should not be applied.
+     * @param args The stash arguments.
+     */
+    static async acquireLocks(args) {
+        const shared = this.queryLocks(args, LockState.Shared, LockOrigin.Acquired);
+        await args.db.locks.acquireLocks({ shared });
+        const exclusive = this.queryLocks(args, LockState.Exclusive, LockOrigin.Acquired);
+        await args.db.locks.acquireLocks({ exclusive });
+        const newElements = this.queryLocks(args, LockState.Shared, LockOrigin.NewElement);
+        for (const id of newElements) {
+            if (!args.db.locks.holdsExclusiveLock(id)) {
+                args.db.locks[_elementWasCreated](id);
+            }
+        }
+    }
+    /**
+     * Creates a stash of changes for the specified briefcase.
+     *
+     * This method generates a stash in the stash root directory for the given briefcase, using the provided description and iModelId.
+     * Optionally, it can reset the briefcase by releasing all locks after stashing.
+     *
+     * @param args - The properties required to create a stash, including the briefcase, description, iModelId, and an optional resetBriefcase flag.
+     * @returns A promise that resolves to the properties of the created stash.
+     */
+    static async stash(args) {
+        if (!args.db.txns.hasPendingTxns) {
+            throw new StashError("nothing to stash");
+        }
+        if (args.db.txns.hasUnsavedChanges) {
+            throw new StashError("Unsaved changes exist");
+        }
+        if (args.db.txns.hasPendingSchemaChanges) {
+            throw new StashError("Pending schema changeset. Stashing is not currently supported for schema changes");
+        }
+        const stashRootDir = this.getStashRootFolder(args.db, true);
+        const iModelId = args.db.iModelId;
+        const stash = args.db[_nativeDb].stashChanges({ stashRootDir, description: args.description, iModelId });
+        if (args.discardLocalChanges) {
+            await args.db.discardChanges({ retainLocks: args.retainLocks });
+        }
+        Logger.logInfo(loggerCategory, `Stashed changes`, () => stash);
+        return stash;
+    }
+    /**
+     * Retrieves the stash properties from the database for the given arguments.
+     *
+     * @param args - The arguments required to locate and access the stash.
+     * @returns The stash file properties if found; otherwise, `undefined`.
+     */
+    static tryGetStash(args) {
+        try {
+            return this.getStash(args);
+        }
+        catch (error) {
+            Logger.logError(loggerCategory, `Error getting stash with ${this.getStashId(args)}: ${error.message}`);
+        }
+        return undefined;
+    }
+    /**
+     * Retrieves the stash properties from the database using the provided arguments.
+     *
+     * @param args - The arguments required to access the stash.
+     * @returns The stash properties parsed from the database.
+     */
+    static getStash(args) {
+        return this.withStash(args, (stashDb) => {
+            const stashProps = stashDb.withPreparedSqliteStatement("SELECT [val] FROM [be_Local] WHERE [name]='$stash_info'", (stmt) => {
+                if (stmt.step() !== DbResult.BE_SQLITE_ROW)
+                    throw new StashError("Invalid stash");
+                return JSON.parse(stmt.getValueString(0));
+            });
+            return stashProps;
+        });
+    }
+    /**
+     * Executes a callback function with a read-only SQLite database connection to a stash file.
+     *
+     * @typeParam T - The return type of the callback function.
+     * @param args - Arguments required to determine the stash file path.
+     * @param callback - A function that receives an open {@link SQLiteDb} instance connected to the stash file.
+     * @returns The value returned by the callback function.
+     */
+    static withStash(args, callback) {
+        const stashFile = this.getStashFilePath(args);
+        if (!existsSync(stashFile)) {
+            throw new StashError("Invalid stash");
+        }
+        const stashDb = new SQLiteDb();
+        stashDb.openDb(stashFile, OpenMode.Readonly);
+        try {
+            return callback(stashDb);
+        }
+        finally {
+            stashDb.closeDb();
+        }
+    }
+    /**
+     * Retrieves all stash files associated with the specified {@link BriefcaseDb}.
+     * @param db - The {@link BriefcaseDb} instance for which to retrieve stash files.
+     * @returns An array of `StashProps` representing the found stash files, sorted by timestamp.
+     */
+    static getStashes(db) {
+        const stashes = [];
+        const stashDir = this.getStashRootFolder(db, false);
+        if (!existsSync(stashDir)) {
+            return stashes;
+        }
+        readdirSync(stashDir).filter((file) => {
+            const filePath = path.join(stashDir, file);
+            if (existsSync(filePath) && statSync(filePath).isFile() && file.endsWith(".stash")) {
+                const id = file.slice(0, -path.extname(file).length);
+                const stash = this.tryGetStash({ db, stash: id });
+                if (stash) {
+                    stashes.push(stash);
+                }
+            }
+        });
+        stashes.sort((a, b) => Date.parse(b.timestamp) - Date.parse(a.timestamp));
+        return stashes;
+    }
+    /**
+     * Deletes the stash file associated with the specified stash ID or properties from the given {@link BriefcaseDb}.
+     *
+     * @param db - The {@link BriefcaseDb} instance from which the stash should be dropped.
+     * @param stashId - The unique identifier (GuidString) or properties (StashProps) of the stash to be deleted.
+     * @returns Returns `true` if the stash file was successfully deleted, otherwise returns `false`.
+     */
+    static dropStash(args) {
+        try {
+            const stashFile = this.getStashFilePath(args);
+            unlinkSync(stashFile);
+            return true;
+        }
+        catch (error) {
+            Logger.logError(loggerCategory, `Error dropping stash: ${error}`);
+        }
+        return false;
+    }
+    /**
+     * Removes all stashes associated with the specified {@link BriefcaseDb}.
+     *
+     * @param db - The {@link BriefcaseDb} instance from which all stashes will be removed.
+     */
+    static dropAllStashes(db) {
+        this.getStashes(db).forEach((stash) => {
+            this.dropStash({ db, stash });
+        });
+    }
+    /**
+     * Queries the hub for the changeset information associated with the given stash.
+     *
+     * @param args - The arguments including the stash properties.
+     * @returns A promise resolving to the changeset ID and index.
+     */
+    static async queryChangeset(args) {
+        return IModelHost[_hubAccess].queryChangeset({
+            iModelId: args.stash.iModelId,
+            changeset: args.stash.parentChangeset,
+            accessToken: await IModelHost.getAccessToken()
+        });
+    }
+    /**
+     * Restores the specified stash to the given {@link BriefcaseDb}. This operation will discard any local changes made to db and reverse the tip to the state of the stash and then apply stash. This will restore the undo stack.
+     *
+     * @param args - The arguments including the target database and stash properties.
+     */
+    static async restore(args) {
+        const { db } = args;
+        Logger.logInfo(loggerCategory, `Restoring stash: ${this.getStashId(args)}`);
+        const stash = this.tryGetStash(args);
+        if (!stash) {
+            throw new StashError(`Stash not found ${this.getStashId(args)}`);
+        }
+        if (db.txns.hasUnsavedChanges) {
+            throw new StashError(`Unsaved changes present`);
+        }
+        if (db.iModelId !== stash.iModelId) {
+            throw new StashError(`Stash does not belong to this iModel`);
+        }
+        if (db.briefcaseId !== stash.briefcaseId) {
+            throw new StashError(`Stash does not belong to this briefcase`);
+        }
+        const stashFile = this.getStashFilePath({ db, stash });
+        // we need to retain lock that overlapped with stash locks instead of all locks
+        await db.discardChanges({ retainLocks: true });
+        await this.acquireLocks(args);
+        if (db.changeset.id !== stash.parentChangeset.id) {
+            // Changeset ID mismatch
+            Logger.logWarning(loggerCategory, "Changeset ID mismatch");
+            const stashChangeset = await this.queryChangeset({ db, stash });
+            await BriefcaseManager.pullAndApplyChangesets(db, { toIndex: stashChangeset.index });
+        }
+        db[_nativeDb].stashRestore(stashFile);
+        db[_resetIModelDb]();
+        db.saveChanges();
+        Logger.logInfo(loggerCategory, `Restored stash: ${this.getStashId(args)}`);
+    }
+}
+//# sourceMappingURL=StashManager.js.map

package/lib/esm/StashManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StashManager.js","sourceRoot":"","sources":["../../src/StashManager.ts"],"names":[],"mappings":"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","sourcesContent":["import { DbResult, GuidString, Id64Array, Id64String, Logger, OpenMode } from \"@itwin/core-bentley\";\nimport { ChangesetIdWithIndex, LocalDirName, LockState } from \"@itwin/core-common\";\nimport { existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from \"node:fs\";\nimport * as path from \"node:path\";\nimport { BriefcaseManager } from \"./BriefcaseManager\";\nimport { BriefcaseDb } from \"./IModelDb\";\nimport { _elementWasCreated, _getHubAccess, _hubAccess, _nativeDb, _resetIModelDb } from \"./internal/Symbols\";\nimport { SQLiteDb } from \"./SQLiteDb\";\nimport { TxnProps } from \"./TxnManager\";\nimport { IModelHost } from \"./IModelHost\";\nimport { BackendLoggerCategory } from \"./BackendLoggerCategory\";\n\nconst loggerCategory = BackendLoggerCategory.StashManager;\n\n/**\n * Custom error class for stash-related errors.\n * @internal\n */\nexport class StashError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"StashError\";\n    Logger.logError(loggerCategory, message);\n  }\n}\n\n/**\n * Properties of a stash\n * @internal\n */\nexport interface StashProps {\n  /** Unique identifier for the stash */\n  readonly id: GuidString;\n\n  /** ID of the iModel being stashed */\n  readonly iModelId: GuidString;\n\n  /** ID of the briefcase being stashed */\n  readonly briefcaseId: number;\n\n  /** ISO local Timestamp of the stash */\n  readonly timestamp: string;\n\n  /** Description of the stash */\n  readonly description: string;\n\n  /** Hash of the stash */\n  readonly hash: string;\n\n  /** Parent changeset of the stash */\n  readonly parentChangeset: ChangesetIdWithIndex;\n\n  /** ID sequences for the stash */\n  readonly idSequences: {\n    element: Id64String;\n    instance: Id64String;\n  };\n\n  /** Transaction properties for the stash */\n  readonly txns: TxnProps[];\n\n  /** Number of locks acquired by the stash */\n  readonly acquiredLocks: number;\n}\n\n/**\n * Properties for creating a stash\n * @internal\n */\nexport interface CreateStashProps {\n  /** Briefcase database instance */\n  readonly db: BriefcaseDb;\n  /** description of the stash */\n  readonly description: string;\n  /** discard all local changes and unless retainLocks flag is set, all locks will be released */\n  readonly discardLocalChanges?: true;\n  /** retains all locks after discarding local changes */\n  readonly retainLocks?: true;\n}\n\n/**\n * Arguments for stash operations\n * @internal\n */\nexport interface StashArgs {\n  readonly db: BriefcaseDb;\n  readonly stash: Id64String | StashProps;\n}\n\nenum LockOrigin {\n  Acquired = 0,\n  NewElement = 1,\n  Discovered = 2,\n};\n\n/**\n * Stash manager allow stash, drop, apply and merge stashes\n * @internal\n */\nexport class StashManager {\n\n  private static readonly STASHES_ROOT_DIR_NAME: string = \".stashes\";\n  /**\n   * Retrieves the root folder path for stash files associated with the specified BriefcaseDb.\n   *\n   * @param db - The BriefcaseDb instance for which to determine the stash root folder.\n   * @param ensureExists - If true, the stash root directory will be created if it does not already exist.\n   * @returns The absolute path to the stash root directory.\n   */\n  private static getStashRootFolder(db: BriefcaseDb, ensureExists: boolean): LocalDirName {\n    if (!db.isOpen || db.isReadonly)\n      throw new StashError(\"Database is not open or is readonly\");\n\n    if (!existsSync(db[_nativeDb].getFilePath())) {\n      throw new StashError(\"Could not determine briefcase path\");\n    }\n\n    const stashDir = path.join(path.dirname(db[_nativeDb].getFilePath()), this.STASHES_ROOT_DIR_NAME, `${db.briefcaseId}`);\n    if (ensureExists && !existsSync(stashDir)) {\n      mkdirSync(stashDir, { recursive: true });\n    }\n    return stashDir;\n  }\n\n  /**\n   * Retrieves the stash ID from the provided arguments.\n   *\n   * If the `stash` property of `args` is a string, it returns the string in lowercase.\n   * If the `stash` property is an object, it returns the `id` property of the object in lowercase.\n   *\n   * @param args - The arguments containing the stash information, which can be either a string or an object with an `id` property.\n   * @returns The stash ID as a lowercase string.\n   */\n  private static getStashId(args: StashArgs) {\n    return (typeof args.stash === \"string\" ? args.stash : args.stash.id).toLowerCase();\n  }\n\n  /**\n   * Retrieves the file path to the stash file associated with the provided arguments.\n   *\n   * @param args - The arguments required to identify the stash, including the database reference.\n   * @returns The absolute path to the stash file.\n   */\n  private static getStashFilePath(args: StashArgs) {\n    const stashRoot = this.getStashRootFolder(args.db, false);\n    if (!existsSync(stashRoot)) {\n      throw new StashError(\"Invalid stash\");\n    }\n\n    const stashFilePath = path.join(stashRoot, `${this.getStashId(args)}.stash`);\n    if (!existsSync(stashFilePath)) {\n      throw new StashError(\"Invalid stash\");\n    }\n    return stashFilePath;\n  }\n\n  /**\n   * Queries the stash database for lock IDs matching the specified state and origin.\n   *\n   * @param args - The arguments required to access the stash database.\n   * @param state - The lock state to filter by.\n   * @param origin - The lock origin to filter by.\n   * @returns An array of lock IDs (`Id64Array`) that match the given state and origin.\n   */\n  private static queryLocks(args: StashArgs, state: LockState, origin: LockOrigin): Id64Array {\n    return this.withStash(args, (stashDb) => {\n      const query = `SELECT JSON_GROUP_ARRAY(FORMAT('0x%x', Id)) FROM [locks] WHERE State = ${state} AND origin = ${origin}`;\n      return stashDb.withPreparedSqliteStatement(query, (stmt) => {\n        if (stmt.step() === DbResult.BE_SQLITE_ROW) {\n          return JSON.parse(stmt.getValueString(0)) as Id64Array;\n        }\n        return [];\n      });\n    });\n  }\n\n  /**\n   * Acquire locks for the specified stash. If this fail then stash should not be applied.\n   * @param args The stash arguments.\n   */\n  private static async acquireLocks(args: StashArgs) {\n    const shared = this.queryLocks(args, LockState.Shared, LockOrigin.Acquired);\n    await args.db.locks.acquireLocks({ shared });\n\n    const exclusive = this.queryLocks(args, LockState.Exclusive, LockOrigin.Acquired);\n    await args.db.locks.acquireLocks({ exclusive });\n\n    const newElements = this.queryLocks(args, LockState.Shared, LockOrigin.NewElement);\n    for (const id of newElements) {\n      if (!args.db.locks.holdsExclusiveLock(id)) {\n        args.db.locks[_elementWasCreated](id);\n      }\n    }\n  }\n  /**\n   * Creates a stash of changes for the specified briefcase.\n   *\n   * This method generates a stash in the stash root directory for the given briefcase, using the provided description and iModelId.\n   * Optionally, it can reset the briefcase by releasing all locks after stashing.\n   *\n   * @param args - The properties required to create a stash, including the briefcase, description, iModelId, and an optional resetBriefcase flag.\n   * @returns A promise that resolves to the properties of the created stash.\n   */\n  public static async stash(args: CreateStashProps): Promise<StashProps> {\n    if (!args.db.txns.hasPendingTxns) {\n      throw new StashError(\"nothing to stash\");\n    }\n\n    if (args.db.txns.hasUnsavedChanges) {\n      throw new StashError(\"Unsaved changes exist\");\n    }\n\n    if (args.db.txns.hasPendingSchemaChanges) {\n      throw new StashError(\"Pending schema changeset. Stashing is not currently supported for schema changes\");\n    }\n\n    const stashRootDir = this.getStashRootFolder(args.db, true);\n    const iModelId = args.db.iModelId;\n    const stash = args.db[_nativeDb].stashChanges({ stashRootDir, description: args.description, iModelId }) as StashProps;\n    if (args.discardLocalChanges) {\n      await args.db.discardChanges({ retainLocks: args.retainLocks });\n    }\n\n    Logger.logInfo(loggerCategory, `Stashed changes`, () => stash);\n    return stash;\n  }\n\n  /**\n   * Retrieves the stash properties from the database for the given arguments.\n   *\n   * @param args - The arguments required to locate and access the stash.\n   * @returns The stash file properties if found; otherwise, `undefined`.\n   */\n  public static tryGetStash(args: StashArgs): StashProps | undefined {\n    try {\n      return this.getStash(args);\n    } catch (error: any) {\n      Logger.logError(loggerCategory, `Error getting stash with ${this.getStashId(args)}: ${error.message}`);\n    }\n    return undefined;\n  }\n\n  /**\n   * Retrieves the stash properties from the database using the provided arguments.\n   *\n   * @param args - The arguments required to access the stash.\n   * @returns The stash properties parsed from the database.\n   */\n  public static getStash(args: StashArgs): StashProps {\n    return this.withStash(args, (stashDb) => {\n      const stashProps = stashDb.withPreparedSqliteStatement(\"SELECT [val] FROM [be_Local] WHERE [name]='$stash_info'\", (stmt) => {\n        if (stmt.step() !== DbResult.BE_SQLITE_ROW)\n          throw new StashError(\"Invalid stash\");\n        return JSON.parse(stmt.getValueString(0)) as StashProps;\n      });\n      return stashProps;\n    });\n  }\n\n  /**\n   * Executes a callback function with a read-only SQLite database connection to a stash file.\n   *\n   * @typeParam T - The return type of the callback function.\n   * @param args - Arguments required to determine the stash file path.\n   * @param callback - A function that receives an open {@link SQLiteDb} instance connected to the stash file.\n   * @returns The value returned by the callback function.\n   */\n  private static withStash<T>(args: StashArgs, callback: (stashDb: SQLiteDb) => T): T {\n    const stashFile = this.getStashFilePath(args);\n    if (!existsSync(stashFile)) {\n      throw new StashError(\"Invalid stash\");\n    }\n\n    const stashDb = new SQLiteDb();\n    stashDb.openDb(stashFile, OpenMode.Readonly);\n    try {\n      return callback(stashDb);\n    } finally {\n      stashDb.closeDb();\n    }\n  }\n\n  /**\n   * Retrieves all stash files associated with the specified {@link BriefcaseDb}.\n   * @param db - The {@link BriefcaseDb} instance for which to retrieve stash files.\n   * @returns An array of `StashProps` representing the found stash files, sorted by timestamp.\n   */\n  public static getStashes(db: BriefcaseDb): StashProps[] {\n    const stashes: StashProps[] = [];\n    const stashDir = this.getStashRootFolder(db, false);\n    if (!existsSync(stashDir)) {\n      return stashes;\n    }\n    readdirSync(stashDir).filter((file) => {\n      const filePath = path.join(stashDir, file);\n      if (existsSync(filePath) && statSync(filePath).isFile() && file.endsWith(\".stash\")) {\n        const id = file.slice(0, -path.extname(file).length)\n        const stash = this.tryGetStash({ db, stash: id });\n        if (stash) {\n          stashes.push(stash);\n        }\n      }\n    });\n    stashes.sort((a, b) => Date.parse(b.timestamp) - Date.parse(a.timestamp));\n    return stashes;\n  }\n\n  /**\n   * Deletes the stash file associated with the specified stash ID or properties from the given {@link BriefcaseDb}.\n   *\n   * @param db - The {@link BriefcaseDb} instance from which the stash should be dropped.\n   * @param stashId - The unique identifier (GuidString) or properties (StashProps) of the stash to be deleted.\n   * @returns Returns `true` if the stash file was successfully deleted, otherwise returns `false`.\n   */\n  public static dropStash(args: StashArgs): boolean {\n    try {\n      const stashFile = this.getStashFilePath(args);\n      unlinkSync(stashFile);\n      return true;\n    } catch (error: any) {\n      Logger.logError(loggerCategory, `Error dropping stash: ${error}`);\n    }\n    return false;\n  }\n\n  /**\n   * Removes all stashes associated with the specified {@link BriefcaseDb}.\n   *\n   * @param db - The {@link BriefcaseDb} instance from which all stashes will be removed.\n   */\n  public static dropAllStashes(db: BriefcaseDb): void {\n    this.getStashes(db).forEach((stash) => {\n      this.dropStash({ db, stash });\n    });\n  }\n\n  /**\n   * Queries the hub for the changeset information associated with the given stash.\n   *\n   * @param args - The arguments including the stash properties.\n   * @returns A promise resolving to the changeset ID and index.\n   */\n  private static async queryChangeset(args: StashArgs & { stash: StashProps }): Promise<ChangesetIdWithIndex> {\n    return IModelHost[_hubAccess].queryChangeset({\n      iModelId: args.stash.iModelId,\n      changeset: args.stash.parentChangeset,\n      accessToken: await IModelHost.getAccessToken()\n    });\n  }\n  /**\n   * Restores the specified stash to the given {@link BriefcaseDb}. This operation will discard any local changes made to db and reverse the tip to the state of the stash and then apply stash. This will restore the undo stack.\n   *\n   * @param args - The arguments including the target database and stash properties.\n   */\n  public static async restore(args: StashArgs): Promise<void> {\n    const { db } = args;\n    Logger.logInfo(loggerCategory, `Restoring stash: ${this.getStashId(args)}`);\n\n    const stash = this.tryGetStash(args);\n    if (!stash) {\n      throw new StashError(`Stash not found ${this.getStashId(args)}`);\n    }\n\n    if (db.txns.hasUnsavedChanges) {\n      throw new StashError(`Unsaved changes present`);\n    }\n\n    if (db.iModelId !== stash.iModelId) {\n      throw new StashError(`Stash does not belong to this iModel`);\n    }\n\n    if (db.briefcaseId !== stash.briefcaseId) {\n      throw new StashError(`Stash does not belong to this briefcase`);\n    }\n\n    const stashFile = this.getStashFilePath({ db, stash });\n    // we need to retain lock that overlapped with stash locks instead of all locks\n    await db.discardChanges({ retainLocks: true });\n    await this.acquireLocks(args);\n    if (db.changeset.id !== stash.parentChangeset.id) {\n      // Changeset ID mismatch\n      Logger.logWarning(loggerCategory, \"Changeset ID mismatch\");\n      const stashChangeset = await this.queryChangeset({ db, stash });\n      await BriefcaseManager.pullAndApplyChangesets(db, { toIndex: stashChangeset.index });\n    }\n\n    db[_nativeDb].stashRestore(stashFile);\n    db[_resetIModelDb]();\n    db.saveChanges();\n    Logger.logInfo(loggerCategory, `Restored stash: ${this.getStashId(args)}`);\n  }\n}\n"]}

package/lib/esm/TxnManager.d.ts

@@ -3,9 +3,9 @@
  */
 import { BeEvent, DbConflictResolution, DbResult, Id64String, IModelStatus } from "@itwin/core-bentley";
 import { EntityIdAndClassIdIterable, ModelGeometryChangesProps, ModelIdAndGeometryGuid } from "@itwin/core-common";
-import { BriefcaseDb, StandaloneDb } from "./IModelDb";
+import { BriefcaseDb, SaveChangesArgs, StandaloneDb } from "./IModelDb";
 import { RelationshipProps } from "./Relationship";
-import { DbRebaseChangesetConflictArgs, RebaseChangesetConflictArgs, TxnArgs } from "./internal/ChangesetConflictArgs";
+import { DbRebaseChangesetConflictArgs, RebaseChangesetConflictArgs } from "./internal/ChangesetConflictArgs";
 /** A string that identifies a Txn.
  * @public @preview
  */
@@ -58,20 +58,163 @@ export interface ChangeInstanceKey {
 /** Strictly for tests. @internal */
 export declare function setMaxEntitiesPerEvent(max: number): number;
 /**
- * @internal
- * Manages conflict resolution during a merge operation.
-*/
-export declare class ChangeMergeManager {
+ * @alpha
+ * Transaction types
+ */
+export type TxnType = "Data" | "ECSchema" | "Ddl";
+/**
+ * @alpha
+ * Transaction modes
+ */
+export type TxnMode = "direct" | "indirect";
+/**
+ * @alpha
+ * Represents the properties of a transaction within the transaction manager.
+ *
+ * @property id - The unique identifier for the transaction.
+ * @property sessionId - The identifier of the session to which the transaction belongs.
+ * @property nextId - (Optional) The identifier of the next transaction in the sequence.
+ * @property prevId - (Optional) The identifier of the previous transaction in the sequence.
+ * @property props - The arguments or properties associated with the save changes operation.
+ * @property type - The type of transaction, which can be "Data", "ECSchema", or "Ddl".
+ * @property reversed - Indicates whether the transaction has been reversed.
+ * @property grouped - Indicates whether the transaction is grouped with others.
+ * @property timestamp - The timestamp when the transaction was created.
+ */
+export interface TxnProps {
+    id: TxnIdString;
+    sessionId: number;
+    nextId?: TxnIdString;
+    prevId?: TxnIdString;
+    props: SaveChangesArgs;
+    type: TxnType;
+    reversed: boolean;
+    grouped: boolean;
+    timestamp: string;
+}
+/**
+ * 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
+ */
+export declare class RebaseManager {
     private _iModel;
     private _conflictHandlers?;
+    private _customHandler?;
     constructor(_iModel: BriefcaseDb | StandaloneDb);
-    resume(): void;
+    /**
+     * 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.
+     */
+    resume(): Promise<void>;
+    /**
+     * 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(): boolean;
+    /**
+     * 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.
+     */
+    abort(): Promise<void>;
+    /**
+     * Sets the handler to be invoked for rebase operations.
+     *
+     * @param handler - The {@link RebaseHandler} to handle rebase events.
+     */
+    setCustomHandler(handler: RebaseHandler): void;
+    /**
+     * Determines whether a transaction is currently in progress.
+     *
+     * @returns {boolean} Returns `true` if there is an active transaction stage, otherwise `false`.
+     */
     inProgress(): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * 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: RebaseChangesetConflictArgs): DbConflictResolution | 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: {
         id: string;
         handler: (args: RebaseChangesetConflictArgs) => DbConflictResolution | undefined;
     }): void;
+    /**
+     * 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: string): void;
 }
 /** Manages local changes to a [[BriefcaseDb]] or [[StandaloneDb]] via [Txns]($docs/learning/InteractiveEditing.md)
@@ -84,7 +227,7 @@ export declare class TxnManager {
     /** @internal */
     get isDisposed(): boolean;
     /** @internal */
-    readonly changeMergeManager: ChangeMergeManager;
+    readonly rebaser: RebaseManager;
     /** @internal */
     constructor(_iModel: BriefcaseDb | StandaloneDb);
     /** Array of errors from dependency propagation */
@@ -129,9 +272,29 @@ export declare class TxnManager {
     protected _onBeforeUndoRedo(isUndo: boolean): void;
     /** @internal */
     protected _onAfterUndoRedo(isUndo: boolean): void;
-    private _onRebaseTxnBegin;
-    private _onRebaseTxnEnd;
     private _onRebaseLocalTxnConflict;
+    /**
+     * @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: TxnIdString): TxnProps | undefined;
+    /**
+     * @alpha
+     * Iterates over all transactions in the sequence, yielding each transaction's properties.
+     *
+     * @yields {TxnProps} The properties of each transaction in the sequence.
+     */
+    queryTxns(): Generator<TxnProps>;
+    /**
+     * @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(): TxnProps | undefined;
     /** 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.
      */
@@ -178,12 +341,18 @@ export declare class TxnManager {
      * @see [[onReplayExternalTxns]] for the event raised before the changes are applied.
      */
     readonly onReplayedExternalTxns: BeEvent<() => void>;
-    /** @internal */
-    readonly onRebaseTxnBegin: BeEvent<(txn: TxnArgs) => void>;
-    /** @internal */
-    readonly onRebaseTxnEnd: BeEvent<(txn: TxnArgs) => void>;
     /**
-     * if handler is set and it does not return undefiend then default handler will not be called
+     * @alpha
+     * Event raised when a rebase transaction begins.
+     */
+    readonly onRebaseTxnBegin: BeEvent<(txn: TxnProps) => void>;
+    /**
+     * @alpha
+     * Event raised when a rebase transaction ends.
+     */
+    readonly onRebaseTxnEnd: BeEvent<(txn: TxnProps) => void>;
+    /**
+     * if handler is set and it does not return undefined then default handler will not be called
      * @internal
      * */
     appCustomConflictHandler?: (args: DbRebaseChangesetConflictArgs) => DbConflictResolution | undefined;
@@ -259,6 +428,11 @@ export declare class TxnManager {
     queryPreviousTxnId(txnId: TxnIdString): TxnIdString;
     /** Get the Id of the current (tip) transaction.  */
     getCurrentTxnId(): TxnIdString;
+    /**
+     * @alpha
+     * Get the Id of the current session.
+     */
+    getCurrentSessionId(): number;
     /** Get the description that was supplied when the specified transaction was saved. */
     getTxnDescription(txnId: TxnIdString): string;
     /** Test if a TxnId is valid */
@@ -272,6 +446,11 @@ export declare class TxnManager {
      * @see [[IModelDb.saveChanges]]
      */
     get hasUnsavedChanges(): boolean;
+    /**
+     * @alpha
+     * Query if there are any pending schema changes in this IModelDb.
+     */
+    get hasPendingSchemaChanges(): boolean;
     /**
      * 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]]
@@ -292,5 +471,37 @@ export declare class TxnManager {
      * changes to the iModel, for debugging/diagnostic purposes, as reported by [sqlite3session_memory_used](https://www.sqlite.org/session/sqlite3session_memory_used.html).
      */
     getChangeTrackingMemoryUsed(): number;
+    /**
+     * @alpha
+     * Get the current transaction mode.
+     * @returns The current transaction mode, either "direct" or "indirect".
+     */
+    getMode(): TxnMode;
+    /**
+     * @alpha
+     * Execute a series of changes in an indirect transaction.
+     * @param callback The function containing the changes to make.
+     */
+    withIndirectTxnMode(callback: () => void): void;
+}
+/**
+ * Interface for handling rebase operations on transactions.
+ * @alpha
+ */
+export interface RebaseHandler {
+    /**
+     * Determine whether a transaction should be reinstated during a rebase operation.
+     * @param txn The transaction to check.
+     *
+     * @alpha
+     */
+    shouldReinstate(txn: TxnProps): boolean;
+    /**
+     * Recompute the changes for a given transaction.
+     * @param txn The transaction to recompute.
+     *
+     * @alpha
+     */
+    recompute(txn: TxnProps): Promise<void>;
 }
 //# sourceMappingURL=TxnManager.d.ts.map