@itwin/core-backend 3.4.0-dev.48 → 3.4.0-dev.55

package/lib/cjs/BriefcaseManager.js

@@ -1,406 +1,406 @@
-"use strict";
-/*---------------------------------------------------------------------------------------------
-* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
-* See LICENSE.md in the project root for license terms and full copyright notice.
-*--------------------------------------------------------------------------------------------*/
-/** @packageDocumentation
- * @module iModels
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.BriefcaseManager = void 0;
-// cspell:ignore cset csets ecchanges
-const path = require("path");
-const core_bentley_1 = require("@itwin/core-bentley");
-const core_common_1 = require("@itwin/core-common");
-const core_telemetry_1 = require("@itwin/core-telemetry");
-const BackendLoggerCategory_1 = require("./BackendLoggerCategory");
-const CheckpointManager_1 = require("./CheckpointManager");
-const IModelDb_1 = require("./IModelDb");
-const IModelHost_1 = require("./IModelHost");
-const IModelJsFs_1 = require("./IModelJsFs");
-const loggerCategory = BackendLoggerCategory_1.BackendLoggerCategory.IModelDb;
-/** Manages downloading Briefcases and downloading and uploading changesets.
- * @public
- */
-class BriefcaseManager {
-    /** 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 */
-    static getChangeSetsPath(iModelId) { return path.join(this.getIModelPath(iModelId), "changesets"); }
-    /** @internal */
-    static getChangeCachePathName(iModelId) { return path.join(this.getIModelPath(iModelId), iModelId.concat(".bim.ecchanges")); }
-    /** @internal */
-    static getChangedElementsPathName(iModelId) { return path.join(this.getIModelPath(iModelId), iModelId.concat(".bim.elems")); }
-    /** @internal */
-    static getBriefcaseBasePath(iModelId) {
-        return path.join(this.getIModelPath(iModelId), this._briefcaseSubDir);
-    }
-    /** Get the name of the local file that holds, or will hold, a local briefcase in the briefcase cache.
-     * @note The briefcase cache is a local directory established in the call to [[BriefcaseManager.initialize]].
-     * @param briefcase the iModelId and BriefcaseId for the filename
-     * @see getIModelPath
-     */
-    static getFileName(briefcase) {
-        return path.join(this.getBriefcaseBasePath(briefcase.iModelId), `${briefcase.briefcaseId}.bim`);
-    }
-    static setupCacheDir(cacheRootDir) {
-        this._cacheDir = cacheRootDir;
-        IModelJsFs_1.IModelJsFs.recursiveMkDirSync(this._cacheDir);
-    }
-    /** Initialize BriefcaseManager
-     * @param cacheRootDir The root directory for storing a cache of downloaded briefcase files on the local computer.
-     * Briefcases are stored relative to this path in sub-folders organized by IModelId.
-     * @note It is perfectly valid for applications to store briefcases in locations they manage, outside of `cacheRootDir`.
-     */
-    static initialize(cacheRootDir) {
-        if (this._initialized)
-            return;
-        this.setupCacheDir(cacheRootDir);
-        IModelHost_1.IModelHost.onBeforeShutdown.addOnce(this.finalize, this);
-        this._initialized = true;
-    }
-    static finalize() {
-        this._initialized = false;
-    }
-    /** Get a list of the local briefcase held in the briefcase cache, optionally for a single iModelId
-     * @param iModelId if present, only briefcases for this iModelId are returned, otherwise all briefcases for all
-     * iModels in the briefcase cache are returned.
-     * @note usually there should only be one briefcase per iModel.
-     */
-    static getCachedBriefcases(iModelId) {
-        var _a, _b, _c;
-        const briefcaseList = [];
-        const iModelDirs = IModelJsFs_1.IModelJsFs.readdirSync(this._cacheDir);
-        for (const iModelDir of iModelDirs) {
-            if (iModelId && iModelId !== iModelDir)
-                continue;
-            const bcPath = path.join(this._cacheDir, iModelDir, this._briefcaseSubDir);
-            try {
-                if (!((_a = IModelJsFs_1.IModelJsFs.lstatSync(bcPath)) === null || _a === void 0 ? void 0 : _a.isDirectory))
-                    continue;
-            }
-            catch (err) {
-                continue;
-            }
-            const briefcases = IModelJsFs_1.IModelJsFs.readdirSync(bcPath);
-            for (const briefcaseName of briefcases) {
-                if (briefcaseName.endsWith(".bim")) {
-                    try {
-                        const fileName = path.join(bcPath, briefcaseName);
-                        const fileSize = (_c = (_b = IModelJsFs_1.IModelJsFs.lstatSync(fileName)) === null || _b === void 0 ? void 0 : _b.size) !== null && _c !== void 0 ? _c : 0;
-                        const db = IModelDb_1.IModelDb.openDgnDb({ path: fileName }, core_bentley_1.OpenMode.Readonly);
-                        briefcaseList.push({ fileName, iTwinId: db.getITwinId(), iModelId: db.getIModelId(), briefcaseId: db.getBriefcaseId(), changeset: db.getCurrentChangeset(), fileSize });
-                        db.closeIModel();
-                    }
-                    catch (_err) {
-                    }
-                }
-            }
-        }
-        return briefcaseList;
-    }
-    /** Get the root directory for the briefcase cache */
-    static get cacheDir() { return this._cacheDir; }
-    /** Determine whether the supplied briefcaseId is in the range of assigned BriefcaseIds issued by iModelHub
-     * @note this does check whether the id was actually acquired by the caller.
-     */
-    static isValidBriefcaseId(id) {
-        return id >= core_common_1.BriefcaseIdValue.FirstValid && id <= core_common_1.BriefcaseIdValue.LastValid;
-    }
-    /** Acquire a new briefcaseId from iModelHub for the supplied iModelId
-     * @note usually there should only be one briefcase per iModel per user. If a single user acquires more than one briefcaseId,
-     * it's a good idea to supply different aliases for each of them.
-     */
-    static async acquireNewBriefcaseId(arg) {
-        return IModelHost_1.IModelHost.hubAccess.acquireNewBriefcaseId(arg);
-    }
-    /**
-     * Download a new briefcase from iModelHub for the supplied iModelId.
-     *
-     * Briefcases are local files holding a copy of an iModel.
-     * Briefcases may either be specific to an individual user (so that it can be modified to create changesets), or it can be readonly so it can accept but not create changesets.
-     * Every briefcase internally holds its [[BriefcaseId]]. Writeable briefcases have a `BriefcaseId` "assigned" to them by iModelHub. No two users will ever have the same BriefcaseId.
-     * Readonly briefcases are "unassigned" with the special value [[BriefcaseId.Unassigned]].
-     *
-     * Typically a given user will have only one briefcase on their machine for a given iModelId. Rarely, it may be necessary to use more than one
-     * briefcase to make isolated independent sets of changes, but that is exceedingly complicated and rare.
-     *
-     * Callers of this method may supply a BriefcaseId, or if none is supplied, a new one is acquired from iModelHub.
-     *
-     * @param arg The arguments that specify the briefcase file to be downloaded.
-     * @returns The properties of the local briefcase in a Promise that is resolved after the briefcase is fully downloaded and the briefcase file is ready for use via [BriefcaseDb.open]($backend).
-     * @note The location of the local file to hold the briefcase is arbitrary and may be any valid *local* path on your machine. If you don't supply
-     * a filename, the local briefcase cache is used by creating a file with the briefcaseId as its name in the `briefcases` folder below the folder named
-     * for the IModelId.
-     * @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) {
-        var _a, _b, _c, _d, _e;
-        const briefcaseId = arg.briefcaseId = (_a = arg.briefcaseId) !== null && _a !== void 0 ? _a : await this.acquireNewBriefcaseId(arg);
-        const fileName = (_b = arg.fileName) !== null && _b !== void 0 ? _b : this.getFileName(arg);
-        if (IModelJsFs_1.IModelJsFs.existsSync(fileName))
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.FileAlreadyExists, `Briefcase "${fileName}" already exists`);
-        const asOf = (_c = arg.asOf) !== null && _c !== void 0 ? _c : core_common_1.IModelVersion.latest().toJSON();
-        const changeset = await IModelHost_1.IModelHost.hubAccess.getChangesetFromVersion({ ...arg, version: core_common_1.IModelVersion.fromJSON(asOf) });
-        const checkpoint = { ...arg, changeset };
-        await CheckpointManager_1.CheckpointManager.downloadCheckpoint({ localFile: fileName, checkpoint, onProgress: arg.onProgress });
-        const fileSize = (_e = (_d = IModelJsFs_1.IModelJsFs.lstatSync(fileName)) === null || _d === void 0 ? void 0 : _d.size) !== null && _e !== void 0 ? _e : 0;
-        const response = {
-            fileName,
-            briefcaseId,
-            iModelId: arg.iModelId,
-            iTwinId: arg.iTwinId,
-            changeset: checkpoint.changeset,
-            fileSize,
-        };
-        // now open the downloaded checkpoint and reset its BriefcaseId
-        const nativeDb = new IModelHost_1.IModelHost.platform.DgnDb();
-        try {
-            nativeDb.openIModel(fileName, core_bentley_1.OpenMode.ReadWrite);
-        }
-        catch (err) {
-            throw new core_common_1.IModelError(err.errorNumber, `Could not open downloaded briefcase for write access: ${fileName}, err=${err.message}`);
-        }
-        try {
-            nativeDb.resetBriefcaseId(briefcaseId);
-            if (nativeDb.getCurrentChangeset().id !== checkpoint.changeset.id)
-                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.InvalidId, `Downloaded briefcase has wrong changesetId: ${fileName}`);
-        }
-        finally {
-            nativeDb.saveChanges();
-            nativeDb.closeIModel();
-        }
-        return response;
-    }
-    /** Deletes change sets of an iModel from local disk
-     * @internal
-     */
-    static deleteChangeSetsFromLocalDisk(iModelId) {
-        const changesetsPath = BriefcaseManager.getChangeSetsPath(iModelId);
-        BriefcaseManager.deleteFolderAndContents(changesetsPath);
-    }
-    /** Releases a briefcaseId from iModelHub. After this call it is illegal to generate changesets for the released briefcaseId.
-     * @note generally, this method should not be called directly. Instead use [[deleteBriefcaseFiles]].
-     * @see deleteBriefcaseFiles
-     */
-    static async releaseBriefcase(accessToken, briefcase) {
-        if (this.isValidBriefcaseId(briefcase.briefcaseId))
-            return IModelHost_1.IModelHost.hubAccess.releaseBriefcase({ accessToken, iModelId: briefcase.iModelId, briefcaseId: briefcase.briefcaseId });
-    }
-    /**
-     * Delete and clean up a briefcase and all of its associated files. First, this method opens the supplied filename to determine its briefcaseId.
-     * Then, if a requestContext is supplied, it releases a BriefcaseId from iModelHub. Finally it deletes the local briefcase file and
-     * associated files (that is, all files in the same directory that start with the briefcase name).
-     * @param filePath the full file name of the Briefcase to delete
-     * @param accessToken for releasing the briefcaseId
-     */
-    static async deleteBriefcaseFiles(filePath, accessToken) {
-        try {
-            const db = IModelDb_1.IModelDb.openDgnDb({ path: filePath }, core_bentley_1.OpenMode.Readonly);
-            const briefcase = {
-                iModelId: db.getIModelId(),
-                briefcaseId: db.getBriefcaseId(),
-            };
-            db.closeIModel();
-            if (accessToken) {
-                if (this.isValidBriefcaseId(briefcase.briefcaseId)) {
-                    await BriefcaseManager.releaseBriefcase(accessToken, briefcase);
-                }
-            }
-        }
-        catch (error) {
-        }
-        // first try to delete the briefcase file
-        try {
-            if (IModelJsFs_1.IModelJsFs.existsSync(filePath))
-                IModelJsFs_1.IModelJsFs.unlinkSync(filePath);
-        }
-        catch (err) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, `cannot delete briefcase file ${err}`);
-        }
-        // next, delete all files that start with the briefcase's filePath (e.g. "a.bim-locks", "a.bim-journal", etc.)
-        try {
-            const dirName = path.dirname(filePath);
-            const fileName = path.basename(filePath);
-            const files = IModelJsFs_1.IModelJsFs.readdirSync(dirName);
-            for (const file of files) {
-                if (file.startsWith(fileName))
-                    this.deleteFile(path.join(dirName, file)); // don't throw on error
-            }
-        }
-        catch (err) {
-        }
-    }
-    /** Deletes a file
-     *  - Does not throw any error, but logs it instead
-     *  - Returns true if the delete was successful
-     */
-    static deleteFile(pathname) {
-        try {
-            IModelJsFs_1.IModelJsFs.unlinkSync(pathname);
-        }
-        catch (error) {
-            core_bentley_1.Logger.logError(loggerCategory, `Cannot delete file ${pathname}, ${error}`);
-            return false;
-        }
-        return true;
-    }
-    /** Deletes a folder, checking if it's empty
-     *  - Does not throw any error, but logs it instead
-     *  - Returns true if the delete was successful
-     */
-    static deleteFolderIfEmpty(folderPathname) {
-        try {
-            const files = IModelJsFs_1.IModelJsFs.readdirSync(folderPathname);
-            if (files.length > 0)
-                return false;
-            IModelJsFs_1.IModelJsFs.rmdirSync(folderPathname);
-        }
-        catch (error) {
-            core_bentley_1.Logger.logError(loggerCategory, `Cannot delete folder: ${folderPathname}`);
-            return false;
-        }
-        return true;
-    }
-    /** Deletes the contents of a folder, but not the folder itself
-     *  - Does not throw any errors, but logs them.
-     *  - returns true if the delete was successful.
-     */
-    static deleteFolderContents(folderPathname) {
-        var _a;
-        if (!IModelJsFs_1.IModelJsFs.existsSync(folderPathname))
-            return false;
-        let status = true;
-        const files = IModelJsFs_1.IModelJsFs.readdirSync(folderPathname);
-        for (const file of files) {
-            const curPath = path.join(folderPathname, file);
-            const locStatus = ((_a = IModelJsFs_1.IModelJsFs.lstatSync(curPath)) === null || _a === void 0 ? void 0 : _a.isDirectory) ? BriefcaseManager.deleteFolderAndContents(curPath) : BriefcaseManager.deleteFile(curPath);
-            if (!locStatus)
-                status = false;
-        }
-        return status;
-    }
-    /** Deletes a folder and all it's contents.
-     *  - Does not throw any errors, but logs them.
-     *  - returns true if the delete was successful.
-     */
-    static deleteFolderAndContents(folderPathname) {
-        if (!IModelJsFs_1.IModelJsFs.existsSync(folderPathname))
-            return true;
-        let status = false;
-        status = BriefcaseManager.deleteFolderContents(folderPathname);
-        if (!status)
-            return false;
-        status = BriefcaseManager.deleteFolderIfEmpty(folderPathname);
-        return status;
-    }
-    static async applySingleChangeset(db, changesetFile) {
-        if (changesetFile.changesType === core_common_1.ChangesetType.Schema)
-            db.clearCaches(); // for schema changesets, statement caches may become invalid. Do this *before* applying, in case db needs to be closed (open statements hold db open.)
-        db.nativeDb.applyChangeset(changesetFile);
-        db.changeset = db.nativeDb.getCurrentChangeset();
-        // we're done with this changeset, delete it
-        IModelJsFs_1.IModelJsFs.removeSync(changesetFile.pathname);
-    }
-    /** @internal */
-    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
-            throw new core_common_1.IModelError(core_bentley_1.ChangeSetStatus.ApplyError, "Briefcase must be open ReadWrite to process change sets");
-        let currentIndex = db.changeset.index;
-        if (currentIndex === undefined)
-            currentIndex = (await IModelHost_1.IModelHost.hubAccess.queryChangeset({ accessToken: arg.accessToken, iModelId: db.iModelId, changeset: { id: db.changeset.id } })).index;
-        const reverse = (arg.toIndex && arg.toIndex < currentIndex) ? true : false;
-        // Download change sets
-        const changesets = await IModelHost_1.IModelHost.hubAccess.downloadChangesets({
-            accessToken: arg.accessToken,
-            iModelId: db.iModelId,
-            range: { first: reverse ? arg.toIndex + 1 : currentIndex + 1, end: reverse ? currentIndex : arg.toIndex },
-            targetDir: BriefcaseManager.getChangeSetsPath(db.iModelId),
-        });
-        if (changesets.length === 0)
-            return; // nothing to apply
-        if (reverse)
-            changesets.reverse();
-        for (const changeset of changesets)
-            await this.applySingleChangeset(db, changeset);
-        // notify listeners
-        db.notifyChangesetApplied();
-    }
-    /** create a changeset from the current changes, and push it to iModelHub */
-    static async pushChanges(db, arg) {
-        var _a, _b;
-        const changesetProps = db.nativeDb.startCreateChangeset();
-        changesetProps.briefcaseId = db.briefcaseId;
-        changesetProps.description = arg.description;
-        changesetProps.size = (_a = IModelJsFs_1.IModelJsFs.lstatSync(changesetProps.pathname)) === null || _a === void 0 ? void 0 : _a.size;
-        if (!changesetProps.size) // either undefined or 0 means error
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NoContent, "error creating changeset");
-        let retryCount = (_b = arg.pushRetryCount) !== null && _b !== void 0 ? _b : 3;
-        while (true) {
-            try {
-                const accessToken = await IModelHost_1.IModelHost.getAccessToken();
-                const index = await IModelHost_1.IModelHost.hubAccess.pushChangeset({ accessToken, iModelId: db.iModelId, changesetProps });
-                db.nativeDb.completeCreateChangeset({ index });
-                db.changeset = db.nativeDb.getCurrentChangeset();
-                if (!arg.retainLocks)
-                    await db.locks.releaseAllLocks();
-                return;
-            }
-            catch (err) {
-                const shouldRetry = () => {
-                    if (retryCount-- <= 0)
-                        return false;
-                    switch (err.errorNumber) {
-                        case core_bentley_1.IModelHubStatus.AnotherUserPushing:
-                        case core_bentley_1.IModelHubStatus.DatabaseTemporarilyLocked:
-                        case core_bentley_1.IModelHubStatus.OperationFailed:
-                            return true;
-                    }
-                    return false;
-                };
-                if (!shouldRetry()) {
-                    db.nativeDb.abandonCreateChangeset();
-                    throw err;
-                }
-            }
-            finally {
-                IModelJsFs_1.IModelJsFs.removeSync(changesetProps.pathname);
-            }
-        }
-    }
-    /** Pull/merge (if necessary), then push all local changes as a changeset. Called by [[BriefcaseDb.pushChanges]]
-     * @internal
-     */
-    static async pullMergePush(db, arg) {
-        var _a, _b;
-        let retryCount = (_a = arg.mergeRetryCount) !== null && _a !== void 0 ? _a : 5;
-        while (true) {
-            try {
-                await BriefcaseManager.pullAndApplyChangesets(db, arg);
-                return await BriefcaseManager.pushChanges(db, arg);
-            }
-            catch (err) {
-                if (retryCount-- <= 0 || err.errorNumber !== core_bentley_1.IModelHubStatus.PullIsRequired)
-                    throw (err);
-                await ((_b = arg.mergeRetryDelay) !== null && _b !== void 0 ? _b : core_bentley_1.BeDuration.fromSeconds(3)).wait();
-            }
-        }
-    }
-    /** @internal */
-    static logUsage(imodel, activity) {
-        var _a;
-        const telemetryEvent = new core_telemetry_1.TelemetryEvent("core-backend - Open iModel", "7a6424d1-2114-4e89-b13b-43670a38ccd4", // Feature: "iModel Use"
-        imodel.iTwinId, imodel.iModelId, (_a = imodel.changeset) === null || _a === void 0 ? void 0 : _a.id);
-        activity = activity !== null && activity !== void 0 ? activity : {
-            activityId: "",
-            applicationId: IModelHost_1.IModelHost.applicationId,
-            applicationVersion: IModelHost_1.IModelHost.applicationVersion,
-            sessionId: IModelHost_1.IModelHost.sessionId,
-            accessToken: "", // IModelHost.getAccessToken(); ACCESS_TOKEN_NEEDS_WORK
-        };
-        IModelHost_1.IModelHost.telemetry.postTelemetry(activity, telemetryEvent); // eslint-disable-line @typescript-eslint/no-floating-promises
-    }
-}
-exports.BriefcaseManager = BriefcaseManager;
-BriefcaseManager._briefcaseSubDir = "briefcases";
+"use strict";
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module iModels
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BriefcaseManager = void 0;
+// cspell:ignore cset csets ecchanges
+const path = require("path");
+const core_bentley_1 = require("@itwin/core-bentley");
+const core_common_1 = require("@itwin/core-common");
+const core_telemetry_1 = require("@itwin/core-telemetry");
+const BackendLoggerCategory_1 = require("./BackendLoggerCategory");
+const CheckpointManager_1 = require("./CheckpointManager");
+const IModelDb_1 = require("./IModelDb");
+const IModelHost_1 = require("./IModelHost");
+const IModelJsFs_1 = require("./IModelJsFs");
+const loggerCategory = BackendLoggerCategory_1.BackendLoggerCategory.IModelDb;
+/** Manages downloading Briefcases and downloading and uploading changesets.
+ * @public
+ */
+class BriefcaseManager {
+    /** 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 */
+    static getChangeSetsPath(iModelId) { return path.join(this.getIModelPath(iModelId), "changesets"); }
+    /** @internal */
+    static getChangeCachePathName(iModelId) { return path.join(this.getIModelPath(iModelId), iModelId.concat(".bim.ecchanges")); }
+    /** @internal */
+    static getChangedElementsPathName(iModelId) { return path.join(this.getIModelPath(iModelId), iModelId.concat(".bim.elems")); }
+    /** @internal */
+    static getBriefcaseBasePath(iModelId) {
+        return path.join(this.getIModelPath(iModelId), this._briefcaseSubDir);
+    }
+    /** Get the name of the local file that holds, or will hold, a local briefcase in the briefcase cache.
+     * @note The briefcase cache is a local directory established in the call to [[BriefcaseManager.initialize]].
+     * @param briefcase the iModelId and BriefcaseId for the filename
+     * @see getIModelPath
+     */
+    static getFileName(briefcase) {
+        return path.join(this.getBriefcaseBasePath(briefcase.iModelId), `${briefcase.briefcaseId}.bim`);
+    }
+    static setupCacheDir(cacheRootDir) {
+        this._cacheDir = cacheRootDir;
+        IModelJsFs_1.IModelJsFs.recursiveMkDirSync(this._cacheDir);
+    }
+    /** Initialize BriefcaseManager
+     * @param cacheRootDir The root directory for storing a cache of downloaded briefcase files on the local computer.
+     * Briefcases are stored relative to this path in sub-folders organized by IModelId.
+     * @note It is perfectly valid for applications to store briefcases in locations they manage, outside of `cacheRootDir`.
+     */
+    static initialize(cacheRootDir) {
+        if (this._initialized)
+            return;
+        this.setupCacheDir(cacheRootDir);
+        IModelHost_1.IModelHost.onBeforeShutdown.addOnce(this.finalize, this);
+        this._initialized = true;
+    }
+    static finalize() {
+        this._initialized = false;
+    }
+    /** Get a list of the local briefcase held in the briefcase cache, optionally for a single iModelId
+     * @param iModelId if present, only briefcases for this iModelId are returned, otherwise all briefcases for all
+     * iModels in the briefcase cache are returned.
+     * @note usually there should only be one briefcase per iModel.
+     */
+    static getCachedBriefcases(iModelId) {
+        var _a, _b, _c;
+        const briefcaseList = [];
+        const iModelDirs = IModelJsFs_1.IModelJsFs.readdirSync(this._cacheDir);
+        for (const iModelDir of iModelDirs) {
+            if (iModelId && iModelId !== iModelDir)
+                continue;
+            const bcPath = path.join(this._cacheDir, iModelDir, this._briefcaseSubDir);
+            try {
+                if (!((_a = IModelJsFs_1.IModelJsFs.lstatSync(bcPath)) === null || _a === void 0 ? void 0 : _a.isDirectory))
+                    continue;
+            }
+            catch (err) {
+                continue;
+            }
+            const briefcases = IModelJsFs_1.IModelJsFs.readdirSync(bcPath);
+            for (const briefcaseName of briefcases) {
+                if (briefcaseName.endsWith(".bim")) {
+                    try {
+                        const fileName = path.join(bcPath, briefcaseName);
+                        const fileSize = (_c = (_b = IModelJsFs_1.IModelJsFs.lstatSync(fileName)) === null || _b === void 0 ? void 0 : _b.size) !== null && _c !== void 0 ? _c : 0;
+                        const db = IModelDb_1.IModelDb.openDgnDb({ path: fileName }, core_bentley_1.OpenMode.Readonly);
+                        briefcaseList.push({ fileName, iTwinId: db.getITwinId(), iModelId: db.getIModelId(), briefcaseId: db.getBriefcaseId(), changeset: db.getCurrentChangeset(), fileSize });
+                        db.closeIModel();
+                    }
+                    catch (_err) {
+                    }
+                }
+            }
+        }
+        return briefcaseList;
+    }
+    /** Get the root directory for the briefcase cache */
+    static get cacheDir() { return this._cacheDir; }
+    /** Determine whether the supplied briefcaseId is in the range of assigned BriefcaseIds issued by iModelHub
+     * @note this does check whether the id was actually acquired by the caller.
+     */
+    static isValidBriefcaseId(id) {
+        return id >= core_common_1.BriefcaseIdValue.FirstValid && id <= core_common_1.BriefcaseIdValue.LastValid;
+    }
+    /** Acquire a new briefcaseId from iModelHub for the supplied iModelId
+     * @note usually there should only be one briefcase per iModel per user. If a single user acquires more than one briefcaseId,
+     * it's a good idea to supply different aliases for each of them.
+     */
+    static async acquireNewBriefcaseId(arg) {
+        return IModelHost_1.IModelHost.hubAccess.acquireNewBriefcaseId(arg);
+    }
+    /**
+     * Download a new briefcase from iModelHub for the supplied iModelId.
+     *
+     * Briefcases are local files holding a copy of an iModel.
+     * Briefcases may either be specific to an individual user (so that it can be modified to create changesets), or it can be readonly so it can accept but not create changesets.
+     * Every briefcase internally holds its [[BriefcaseId]]. Writeable briefcases have a `BriefcaseId` "assigned" to them by iModelHub. No two users will ever have the same BriefcaseId.
+     * Readonly briefcases are "unassigned" with the special value [[BriefcaseId.Unassigned]].
+     *
+     * Typically a given user will have only one briefcase on their machine for a given iModelId. Rarely, it may be necessary to use more than one
+     * briefcase to make isolated independent sets of changes, but that is exceedingly complicated and rare.
+     *
+     * Callers of this method may supply a BriefcaseId, or if none is supplied, a new one is acquired from iModelHub.
+     *
+     * @param arg The arguments that specify the briefcase file to be downloaded.
+     * @returns The properties of the local briefcase in a Promise that is resolved after the briefcase is fully downloaded and the briefcase file is ready for use via [BriefcaseDb.open]($backend).
+     * @note The location of the local file to hold the briefcase is arbitrary and may be any valid *local* path on your machine. If you don't supply
+     * a filename, the local briefcase cache is used by creating a file with the briefcaseId as its name in the `briefcases` folder below the folder named
+     * for the IModelId.
+     * @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) {
+        var _a, _b, _c, _d, _e;
+        const briefcaseId = arg.briefcaseId = (_a = arg.briefcaseId) !== null && _a !== void 0 ? _a : await this.acquireNewBriefcaseId(arg);
+        const fileName = (_b = arg.fileName) !== null && _b !== void 0 ? _b : this.getFileName(arg);
+        if (IModelJsFs_1.IModelJsFs.existsSync(fileName))
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.FileAlreadyExists, `Briefcase "${fileName}" already exists`);
+        const asOf = (_c = arg.asOf) !== null && _c !== void 0 ? _c : core_common_1.IModelVersion.latest().toJSON();
+        const changeset = await IModelHost_1.IModelHost.hubAccess.getChangesetFromVersion({ ...arg, version: core_common_1.IModelVersion.fromJSON(asOf) });
+        const checkpoint = { ...arg, changeset };
+        await CheckpointManager_1.CheckpointManager.downloadCheckpoint({ localFile: fileName, checkpoint, onProgress: arg.onProgress });
+        const fileSize = (_e = (_d = IModelJsFs_1.IModelJsFs.lstatSync(fileName)) === null || _d === void 0 ? void 0 : _d.size) !== null && _e !== void 0 ? _e : 0;
+        const response = {
+            fileName,
+            briefcaseId,
+            iModelId: arg.iModelId,
+            iTwinId: arg.iTwinId,
+            changeset: checkpoint.changeset,
+            fileSize,
+        };
+        // now open the downloaded checkpoint and reset its BriefcaseId
+        const nativeDb = new IModelHost_1.IModelHost.platform.DgnDb();
+        try {
+            nativeDb.openIModel(fileName, core_bentley_1.OpenMode.ReadWrite);
+        }
+        catch (err) {
+            throw new core_common_1.IModelError(err.errorNumber, `Could not open downloaded briefcase for write access: ${fileName}, err=${err.message}`);
+        }
+        try {
+            nativeDb.resetBriefcaseId(briefcaseId);
+            if (nativeDb.getCurrentChangeset().id !== checkpoint.changeset.id)
+                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.InvalidId, `Downloaded briefcase has wrong changesetId: ${fileName}`);
+        }
+        finally {
+            nativeDb.saveChanges();
+            nativeDb.closeIModel();
+        }
+        return response;
+    }
+    /** Deletes change sets of an iModel from local disk
+     * @internal
+     */
+    static deleteChangeSetsFromLocalDisk(iModelId) {
+        const changesetsPath = BriefcaseManager.getChangeSetsPath(iModelId);
+        BriefcaseManager.deleteFolderAndContents(changesetsPath);
+    }
+    /** Releases a briefcaseId from iModelHub. After this call it is illegal to generate changesets for the released briefcaseId.
+     * @note generally, this method should not be called directly. Instead use [[deleteBriefcaseFiles]].
+     * @see deleteBriefcaseFiles
+     */
+    static async releaseBriefcase(accessToken, briefcase) {
+        if (this.isValidBriefcaseId(briefcase.briefcaseId))
+            return IModelHost_1.IModelHost.hubAccess.releaseBriefcase({ accessToken, iModelId: briefcase.iModelId, briefcaseId: briefcase.briefcaseId });
+    }
+    /**
+     * Delete and clean up a briefcase and all of its associated files. First, this method opens the supplied filename to determine its briefcaseId.
+     * Then, if a requestContext is supplied, it releases a BriefcaseId from iModelHub. Finally it deletes the local briefcase file and
+     * associated files (that is, all files in the same directory that start with the briefcase name).
+     * @param filePath the full file name of the Briefcase to delete
+     * @param accessToken for releasing the briefcaseId
+     */
+    static async deleteBriefcaseFiles(filePath, accessToken) {
+        try {
+            const db = IModelDb_1.IModelDb.openDgnDb({ path: filePath }, core_bentley_1.OpenMode.Readonly);
+            const briefcase = {
+                iModelId: db.getIModelId(),
+                briefcaseId: db.getBriefcaseId(),
+            };
+            db.closeIModel();
+            if (accessToken) {
+                if (this.isValidBriefcaseId(briefcase.briefcaseId)) {
+                    await BriefcaseManager.releaseBriefcase(accessToken, briefcase);
+                }
+            }
+        }
+        catch (error) {
+        }
+        // first try to delete the briefcase file
+        try {
+            if (IModelJsFs_1.IModelJsFs.existsSync(filePath))
+                IModelJsFs_1.IModelJsFs.unlinkSync(filePath);
+        }
+        catch (err) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, `cannot delete briefcase file ${err}`);
+        }
+        // next, delete all files that start with the briefcase's filePath (e.g. "a.bim-locks", "a.bim-journal", etc.)
+        try {
+            const dirName = path.dirname(filePath);
+            const fileName = path.basename(filePath);
+            const files = IModelJsFs_1.IModelJsFs.readdirSync(dirName);
+            for (const file of files) {
+                if (file.startsWith(fileName))
+                    this.deleteFile(path.join(dirName, file)); // don't throw on error
+            }
+        }
+        catch (err) {
+        }
+    }
+    /** Deletes a file
+     *  - Does not throw any error, but logs it instead
+     *  - Returns true if the delete was successful
+     */
+    static deleteFile(pathname) {
+        try {
+            IModelJsFs_1.IModelJsFs.unlinkSync(pathname);
+        }
+        catch (error) {
+            core_bentley_1.Logger.logError(loggerCategory, `Cannot delete file ${pathname}, ${error}`);
+            return false;
+        }
+        return true;
+    }
+    /** Deletes a folder, checking if it's empty
+     *  - Does not throw any error, but logs it instead
+     *  - Returns true if the delete was successful
+     */
+    static deleteFolderIfEmpty(folderPathname) {
+        try {
+            const files = IModelJsFs_1.IModelJsFs.readdirSync(folderPathname);
+            if (files.length > 0)
+                return false;
+            IModelJsFs_1.IModelJsFs.rmdirSync(folderPathname);
+        }
+        catch (error) {
+            core_bentley_1.Logger.logError(loggerCategory, `Cannot delete folder: ${folderPathname}`);
+            return false;
+        }
+        return true;
+    }
+    /** Deletes the contents of a folder, but not the folder itself
+     *  - Does not throw any errors, but logs them.
+     *  - returns true if the delete was successful.
+     */
+    static deleteFolderContents(folderPathname) {
+        var _a;
+        if (!IModelJsFs_1.IModelJsFs.existsSync(folderPathname))
+            return false;
+        let status = true;
+        const files = IModelJsFs_1.IModelJsFs.readdirSync(folderPathname);
+        for (const file of files) {
+            const curPath = path.join(folderPathname, file);
+            const locStatus = ((_a = IModelJsFs_1.IModelJsFs.lstatSync(curPath)) === null || _a === void 0 ? void 0 : _a.isDirectory) ? BriefcaseManager.deleteFolderAndContents(curPath) : BriefcaseManager.deleteFile(curPath);
+            if (!locStatus)
+                status = false;
+        }
+        return status;
+    }
+    /** Deletes a folder and all it's contents.
+     *  - Does not throw any errors, but logs them.
+     *  - returns true if the delete was successful.
+     */
+    static deleteFolderAndContents(folderPathname) {
+        if (!IModelJsFs_1.IModelJsFs.existsSync(folderPathname))
+            return true;
+        let status = false;
+        status = BriefcaseManager.deleteFolderContents(folderPathname);
+        if (!status)
+            return false;
+        status = BriefcaseManager.deleteFolderIfEmpty(folderPathname);
+        return status;
+    }
+    static async applySingleChangeset(db, changesetFile) {
+        if (changesetFile.changesType === core_common_1.ChangesetType.Schema)
+            db.clearCaches(); // for schema changesets, statement caches may become invalid. Do this *before* applying, in case db needs to be closed (open statements hold db open.)
+        db.nativeDb.applyChangeset(changesetFile);
+        db.changeset = db.nativeDb.getCurrentChangeset();
+        // we're done with this changeset, delete it
+        IModelJsFs_1.IModelJsFs.removeSync(changesetFile.pathname);
+    }
+    /** @internal */
+    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
+            throw new core_common_1.IModelError(core_bentley_1.ChangeSetStatus.ApplyError, "Briefcase must be open ReadWrite to process change sets");
+        let currentIndex = db.changeset.index;
+        if (currentIndex === undefined)
+            currentIndex = (await IModelHost_1.IModelHost.hubAccess.queryChangeset({ accessToken: arg.accessToken, iModelId: db.iModelId, changeset: { id: db.changeset.id } })).index;
+        const reverse = (arg.toIndex && arg.toIndex < currentIndex) ? true : false;
+        // Download change sets
+        const changesets = await IModelHost_1.IModelHost.hubAccess.downloadChangesets({
+            accessToken: arg.accessToken,
+            iModelId: db.iModelId,
+            range: { first: reverse ? arg.toIndex + 1 : currentIndex + 1, end: reverse ? currentIndex : arg.toIndex },
+            targetDir: BriefcaseManager.getChangeSetsPath(db.iModelId),
+        });
+        if (changesets.length === 0)
+            return; // nothing to apply
+        if (reverse)
+            changesets.reverse();
+        for (const changeset of changesets)
+            await this.applySingleChangeset(db, changeset);
+        // notify listeners
+        db.notifyChangesetApplied();
+    }
+    /** create a changeset from the current changes, and push it to iModelHub */
+    static async pushChanges(db, arg) {
+        var _a, _b;
+        const changesetProps = db.nativeDb.startCreateChangeset();
+        changesetProps.briefcaseId = db.briefcaseId;
+        changesetProps.description = arg.description;
+        changesetProps.size = (_a = IModelJsFs_1.IModelJsFs.lstatSync(changesetProps.pathname)) === null || _a === void 0 ? void 0 : _a.size;
+        if (!changesetProps.size) // either undefined or 0 means error
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NoContent, "error creating changeset");
+        let retryCount = (_b = arg.pushRetryCount) !== null && _b !== void 0 ? _b : 3;
+        while (true) {
+            try {
+                const accessToken = await IModelHost_1.IModelHost.getAccessToken();
+                const index = await IModelHost_1.IModelHost.hubAccess.pushChangeset({ accessToken, iModelId: db.iModelId, changesetProps });
+                db.nativeDb.completeCreateChangeset({ index });
+                db.changeset = db.nativeDb.getCurrentChangeset();
+                if (!arg.retainLocks)
+                    await db.locks.releaseAllLocks();
+                return;
+            }
+            catch (err) {
+                const shouldRetry = () => {
+                    if (retryCount-- <= 0)
+                        return false;
+                    switch (err.errorNumber) {
+                        case core_bentley_1.IModelHubStatus.AnotherUserPushing:
+                        case core_bentley_1.IModelHubStatus.DatabaseTemporarilyLocked:
+                        case core_bentley_1.IModelHubStatus.OperationFailed:
+                            return true;
+                    }
+                    return false;
+                };
+                if (!shouldRetry()) {
+                    db.nativeDb.abandonCreateChangeset();
+                    throw err;
+                }
+            }
+            finally {
+                IModelJsFs_1.IModelJsFs.removeSync(changesetProps.pathname);
+            }
+        }
+    }
+    /** Pull/merge (if necessary), then push all local changes as a changeset. Called by [[BriefcaseDb.pushChanges]]
+     * @internal
+     */
+    static async pullMergePush(db, arg) {
+        var _a, _b;
+        let retryCount = (_a = arg.mergeRetryCount) !== null && _a !== void 0 ? _a : 5;
+        while (true) {
+            try {
+                await BriefcaseManager.pullAndApplyChangesets(db, arg);
+                return await BriefcaseManager.pushChanges(db, arg);
+            }
+            catch (err) {
+                if (retryCount-- <= 0 || err.errorNumber !== core_bentley_1.IModelHubStatus.PullIsRequired)
+                    throw (err);
+                await ((_b = arg.mergeRetryDelay) !== null && _b !== void 0 ? _b : core_bentley_1.BeDuration.fromSeconds(3)).wait();
+            }
+        }
+    }
+    /** @internal */
+    static logUsage(imodel, activity) {
+        var _a;
+        const telemetryEvent = new core_telemetry_1.TelemetryEvent("core-backend - Open iModel", "7a6424d1-2114-4e89-b13b-43670a38ccd4", // Feature: "iModel Use"
+        imodel.iTwinId, imodel.iModelId, (_a = imodel.changeset) === null || _a === void 0 ? void 0 : _a.id);
+        activity = activity !== null && activity !== void 0 ? activity : {
+            activityId: "",
+            applicationId: IModelHost_1.IModelHost.applicationId,
+            applicationVersion: IModelHost_1.IModelHost.applicationVersion,
+            sessionId: IModelHost_1.IModelHost.sessionId,
+            accessToken: "", // IModelHost.getAccessToken(); ACCESS_TOKEN_NEEDS_WORK
+        };
+        IModelHost_1.IModelHost.telemetry.postTelemetry(activity, telemetryEvent); // eslint-disable-line @typescript-eslint/no-floating-promises
+    }
+}
+exports.BriefcaseManager = BriefcaseManager;
+BriefcaseManager._briefcaseSubDir = "briefcases";
 //# sourceMappingURL=BriefcaseManager.js.map