@itwin/core-backend

/** @packageDocumentation * @module iModels */ import { AccessToken, BeDuration, GuidString, Optional } from "@itwin/core-bentley"; import { BriefcaseId, BriefcaseProps, ChangesetFileProps, ChangesetIndex, ChangesetIndexOrId, ChangesetProps, ChangesetRange, LocalBriefcaseProps, LocalDirName, LocalFileName, RequestNewBriefcaseProps } from "@itwin/core-common"; import { AcquireNewBriefcaseIdArg, DownloadChangesetArg, DownloadChangesetRangeArg, IModelNameArg } from "./BackendHubAccess"; import { ProgressFunction } from "./CheckpointManager"; import { BriefcaseDb, IModelDb, TokenArg } from "./IModelDb"; import { StashProps } from "./StashManager"; import { ChangeInstance, ChangeMeta } from "./ChangesetReaderTypes"; /** The argument for patch instances during semantic rebase * @internal */ export interface InstancePatch extends Omit<ChangeInstance, "$meta"> { $meta: Pick<ChangeMeta, "op" | "stage" | "isIndirectChange">; } /** The argument for [[BriefcaseManager.downloadBriefcase]] * @public */ export interface RequestNewBriefcaseArg extends TokenArg, RequestNewBriefcaseProps { /** If present, a function called periodically during the download to indicate progress. * @note return non-zero from this function to abort the download. */ onProgress?: ProgressFunction; } /** * Parameters for pushing changesets to iModelHub * @public */ export interface PushChangesArgs extends TokenArg { /** A description of the changes. This is visible on the iModel's timeline. */ description: string; /** if present, the locks are retained after the operation. Otherwise, *all* locks are released after the changeset is successfully pushed. */ retainLocks?: true; /** number of times to retry pull/merge if other users are pushing at the same time. Default is 5 */ mergeRetryCount?: number; /** delay to wait between pull/merge retry attempts. Default is 3 seconds */ mergeRetryDelay?: BeDuration; /** the number of time to attempt to retry to push the changeset upon failure. Default is 3 */ pushRetryCount?: number; /** The delay to wait between retry attempts on failed pushes. Default is 3 seconds. */ pushRetryDelay?: BeDuration; /** * (unused) * @deprecated in 5.1.8 - will not be removed until after 2026-10-01. Not used by BriefcaseManager. Caller should remove this flag. * @internal */ noFastForward?: true; } /** * Specifies a specific index for pulling changes. * @public */ export interface ToChangesetArgs extends TokenArg { /** The last ChangesetIndex to pull. If not present, pull *all* newer changesets. */ toIndex?: ChangesetIndex; } /** Arguments for [[BriefcaseManager.pullAndApplyChangesets]] * @public */ export type PullChangesArgs = ToChangesetArgs & { /** If present, a function called periodically during the download to indicate progress. * @note return non-zero from this function to abort the download. */ onProgress?: ProgressFunction; /** * (unused) * @deprecated in 5.1.8 - will not be removed until after 2026-10-01. Not used by BriefcaseManager. Caller should remove this flag. * @internal */ noFastForward?: true; }; /** Arguments for [[BriefcaseManager.revertTimelineChanges]] * @public */ export type RevertChangesArgs = Optional<PushChangesArgs, "description"> & { /** If present, a function called periodically during the download to indicate progress. * @note return non-zero from this function to abort the download. */ onProgress?: ProgressFunction; /** The first changeset index to revert (inclusive). All changesets from `toIndex` through the current index are reverted, leaving the briefcase at `toIndex - 1`. */ toIndex: ChangesetIndex; /** If present, schema changes are skipped during the revert operation. */ skipSchemaChanges?: true; /** * Specifies the action to take in case of failure during the revert operation. Default is `"revert"`. * - `"revert"`: Reverse all local transactions and delete them, restoring the briefcase to its pre-revert state. * - `"retain"`: Keep local changes as-is for caller inspection or manual recovery. * - `"delete"`: Close the briefcase and delete the local file. If an `accessToken` is available, also release the briefcaseId from iModelHub. */ inCaseOfFailure?: "retain" | "revert" | "delete"; }; /** Manages downloading Briefcases and downloading and uploading changesets. * @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 */ static getChangeSetsPath(iModelId: GuidString): LocalDirName; /** @internal */ static getChangeCachePathName(iModelId: GuidString): LocalFileName; /** @internal */ static getChangedElementsPathName(iModelId: GuidString): LocalFileName; private static _briefcaseSubDir; /** Get the local path of the folder storing briefcases associated with the specified iModel. */ static getBriefcaseBasePath(iModelId: GuidString): LocalDirName; /** 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: BriefcaseProps): LocalFileName; private static setupCacheDir; private static _initialized?; /** 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: LocalDirName): void; private static finalize; /** 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?: GuidString): LocalBriefcaseProps[]; private static _cacheDir; /** Get the root directory for the briefcase cache */ static get cacheDir(): LocalDirName; /** 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: BriefcaseId): boolean; /** 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 acquireNewBriefcaseId(arg: AcquireNewBriefcaseIdArg): Promise<BriefcaseId>; /** * 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 downloadBriefcase(arg: RequestNewBriefcaseArg): Promise<LocalBriefcaseProps>; /** Deletes change sets of an iModel from local disk * @internal */ static deleteChangeSetsFromLocalDisk(iModelId: string): void; /** 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 releaseBriefcase(accessToken: AccessToken, briefcase: BriefcaseProps): Promise<void>; /** * 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 deleteBriefcaseFiles(filePath: LocalFileName, accessToken?: AccessToken): Promise<void>; /** Deletes a file * - Does not throw any error, but logs it instead * - Returns true if the delete was successful */ private static deleteFile; /** Deletes a folder, checking if it's empty * - Does not throw any error, but logs it instead * - Returns true if the delete was successful */ private static deleteFolderIfEmpty; /** 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. */ private static deleteFolderContents; /** Download all the changesets in the specified range. * @beta */ static downloadChangesets(arg: DownloadChangesetRangeArg): Promise<ChangesetFileProps[]>; /** Download a single changeset. * @beta */ static downloadChangeset(arg: DownloadChangesetArg): Promise<ChangesetFileProps>; /** Query the hub for the properties for a ChangesetIndex or ChangesetId */ static queryChangeset(arg: { iModelId: GuidString; changeset: ChangesetIndexOrId; }): Promise<ChangesetProps>; /** Query the hub for an array of changeset properties given a ChangesetRange */ static queryChangesets(arg: { iModelId: GuidString; range: ChangesetRange; }): Promise<ChangesetProps[]>; /** Query the hub for the ChangesetProps of the most recent changeset */ static getLatestChangeset(arg: { iModelId: GuidString; }): Promise<ChangesetProps>; /** Query the Id of an iModel by name. * @param arg Identifies the iModel of interest * @returns the Id of the corresponding iModel, or `undefined` if no such iModel exists. */ static queryIModelByName(arg: IModelNameArg): Promise<GuidString | undefined>; /** Deletes a folder and all it's contents. * - Does not throw any errors, but logs them. * - returns true if the delete was successful. */ private static deleteFolderAndContents; private static applySingleChangeset; /** @internal */ static revertTimelineChanges(db: IModelDb, arg: RevertChangesArgs): Promise<void>; /** * @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 & { noUpdateLoop?: boolean; }): 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]] * @internal */ static pullMergePush(db: BriefcaseDb, arg: PushChangesArgs): Promise<void>; private static readonly REBASING_FOLDER; private static readonly EC_FOLDER; private static readonly SCHEMAS_FOLDER; private static readonly DATA_FOLDER; private static readonly DATA_FILE_NAME; /** * Stores changed instances for semantic rebase locally in appropriate json file in a folder structure * @param db The [BriefcaseDb]($backend) instance for storing the changed instances against a txn * @param txnId The txn id for which we are storing the changed instances * @param instancePatches The [ChangeInstance]($backend) IterableIterator instance patches to be stored * @internal */ static storeChangedInstancesForSemanticRebase(db: BriefcaseDb, txnId: string, instancePatches: IterableIterator<ChangeInstance>): void; /** * Gets the base path for semantic rebase local files * @param db The {@link BriefcaseDb} instance for which to get the base path * @returns base path for semantic rebase local files * @internal */ static getBasePathForSemanticRebaseLocalFiles(db: BriefcaseDb): string; /** * Stores schemas for semantic rebase locally in appropriate folder structure * @param db The [BriefcaseDb]($backend) instance for storing the schemas against a txn * @param txnId The txn id for which we are storing the schemas * @param schemaFileNames The schema file paths or schema xml strings to be stored * @internal */ static storeSchemasForSemanticRebase<T extends LocalFileName[] | string[]>(db: BriefcaseDb, txnId: string, schemaFileNames: T): void; /** * Gets schemas for semantic rebase for a txn * @param db The [BriefcaseDb]($backend) instance for getting the locally stored schemas against a txn * @param txnId The txn id for which we are getting the schemas * @returns the schema file paths * @internal */ static getSchemasForTxn(db: BriefcaseDb, txnId: string): string[]; /** * Get the changed instances data for semantic rebase for a txn * @param db - The [BriefcaseDb]($backend) instance for getting the locally stored changed instances against a txn * @param txnId - The txn id for which we are getting the changed instances * @returns Instance patches * @internal */ static getChangedInstancesDataForTxn(db: BriefcaseDb, txnId: string): AsyncGenerator<InstancePatch>; /** * Checks if schema folder exists for semantic rebase for a txn * @param db - The [BriefcaseDb]($backend) instance for which TO check the schema folder * @param txnId - The txn id for which we are check the schema folder * @returns true if exists, false otherwise * @internal */ static semanticRebaseSchemaFolderExists(db: BriefcaseDb, txnId: string): boolean; /** * Checks if data folder exists for semantic rebase for a txn * @param db The [BriefcaseDb]($backend) instance for which to check the data folder. * @param txnId The txn id for which to check the data folder * @returns true if exists, false otherwise * @internal */ static semanticRebaseDataFolderExists(db: BriefcaseDb, txnId: string): boolean; /** * Deletes the schema folder for semantic rebase for a txn * @param db The [BriefcaseDb]($backend) instance for which to delete the schema folder. * @param txnId The txn id for which to delete the schema folder * @internal */ static deleteTxnSchemaFolder(db: BriefcaseDb, txnId: string): void; /** * Deletes the data folder for semantic rebase for a txn * @param db The [BriefcaseDb]($backend) instance for which to delete the data folder. * @param txnId The txn id for which to delete the data folder * @internal */ static deleteTxnDataFolder(db: BriefcaseDb, txnId: string): void; /** * Deletes rebase folders for semantic rebase * @param db The [BriefcaseDb]($backend) instance for which to delete the rebase folders. * @param checkIfEmpty If true, only deletes the base folder if it is empty, default is false * @internal */ static deleteRebaseFolders(db: BriefcaseDb, checkIfEmpty?: boolean): void; /** * Cleans up rebase folders for semantic rebase given briefcase file path and briefcase id * @param briefcaseFilePath The briefcase file path * @param briefcaseId The briefcase id * @internal */ private static cleanupRebaseFolders; } //# sourceMappingURL=BriefcaseManager.d.ts.map