@itwin/core-backend/lib/esm/StashManager.d.ts

iTwin.js backend components

import { GuidString, Id64String, ITwinError } from "@itwin/core-bentley";
import { ChangesetIdWithIndex } from "@itwin/core-common";
import { BriefcaseDb } from "./IModelDb";
import { TxnProps } from "./TxnManager";
/**
 * Properties of a stash
 * @internal
 */
export interface StashProps {
    /** Unique identifier for the stash */
    readonly id: GuidString;
    /** ID of the iModel being stashed */
    readonly iModelId: GuidString;
    /** ID of the briefcase being stashed */
    readonly briefcaseId: number;
    /** ISO local Timestamp of the stash */
    readonly timestamp: string;
    /** Description of the stash */
    readonly description: string;
    /** Hash of the stash */
    readonly hash: string;
    /** Parent changeset of the stash */
    readonly parentChangeset: ChangesetIdWithIndex;
    /** ID sequences for the stash */
    readonly idSequences: {
        element: Id64String;
        instance: Id64String;
    };
    /** Transaction properties for the stash */
    readonly txns: TxnProps[];
    /** Number of locks acquired by the stash */
    readonly acquiredLocks: number;
}
/**
 * Properties for creating a stash
 * @internal
 */
export interface CreateStashProps {
    /** Briefcase database instance */
    readonly db: BriefcaseDb;
    /** description of the stash */
    readonly description: string;
    /** discard all local changes and unless retainLocks flag is set, all locks will be released */
    readonly discardLocalChanges?: true;
    /** retains all locks after discarding local changes */
    readonly retainLocks?: true;
}
/**
 * Arguments for stash operations
 * @internal
 */
export interface StashArgs {
    readonly db: BriefcaseDb;
    readonly stash: Id64String | StashProps;
}
/**
 * An error originating from the StashManager API.
 * @internal
 */
export declare namespace StashError {
    const scope = "itwin-StashManager";
    type Key = "readonly" | "no-file" | "no-stashes" | "invalid-stash" | "nothing-to-stash" | "unsaved-changes" | "pending-schema-changes" | "stash-not-found";
    /** Instantiate and throw a StashError */
    function throwError(key: Key, message: string): never;
    /** Determine whether an error object is a StashError */
    function isError(error: unknown, key?: Key): error is ITwinError;
}
/**
 * Stash manager allow stash, drop, apply and merge stashes
 * @internal
 */
export declare class StashManager {
    private static readonly STASHES_ROOT_DIR_NAME;
    /**
     * 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.
     */
    private static getStashRootFolder;
    /**
     * 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.
     */
    private static getStashId;
    /**
     * 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.
     */
    private static getStashFilePath;
    /**
     * 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.
     */
    private static queryLocks;
    /**
     * Acquire locks for the specified stash. If this fail then stash should not be applied.
     * @param args The stash arguments.
     */
    private static acquireLocks;
    /**
     * 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 stash(args: CreateStashProps): Promise<StashProps>;
    /**
     * 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: StashArgs): StashProps | 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: StashArgs): 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.
     */
    private static withStash;
    /**
     * 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: BriefcaseDb): StashProps[];
    /**
     * 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: StashArgs): boolean;
    /**
     * 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: BriefcaseDb): void;
    /**
     * 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.
     */
    private static queryChangeset;
    /**
     * 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 restore(args: StashArgs): Promise<void>;
}
//# sourceMappingURL=StashManager.d.ts.map