@itwin/core-backend 5.2.0-dev.8 → 5.2.0

package/lib/cjs/StashManager.d.ts

@@ -0,0 +1,175 @@
+import { GuidString, Id64String } from "@itwin/core-bentley";
+import { ChangesetIdWithIndex } from "@itwin/core-common";
+import { BriefcaseDb } from "./IModelDb";
+import { TxnProps } from "./TxnManager";
+/**
+ * Custom error class for stash-related errors.
+ * @internal
+ */
+export declare class StashError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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;
+}
+/**
+ * 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

package/lib/cjs/StashManager.d.ts.map

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

package/lib/cjs/StashManager.js

@@ -0,0 +1,306 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StashManager = exports.StashError = void 0;
+const core_bentley_1 = require("@itwin/core-bentley");
+const core_common_1 = require("@itwin/core-common");
+const node_fs_1 = require("node:fs");
+const path = require("node:path");
+const BriefcaseManager_1 = require("./BriefcaseManager");
+const Symbols_1 = require("./internal/Symbols");
+const SQLiteDb_1 = require("./SQLiteDb");
+const IModelHost_1 = require("./IModelHost");
+const BackendLoggerCategory_1 = require("./BackendLoggerCategory");
+const loggerCategory = BackendLoggerCategory_1.BackendLoggerCategory.StashManager;
+/**
+ * Custom error class for stash-related errors.
+ * @internal
+ */
+class StashError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "StashError";
+        core_bentley_1.Logger.logError(loggerCategory, message);
+    }
+}
+exports.StashError = StashError;
+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
+ */
+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 (!(0, node_fs_1.existsSync)(db[Symbols_1._nativeDb].getFilePath())) {
+            throw new StashError("Could not determine briefcase path");
+        }
+        const stashDir = path.join(path.dirname(db[Symbols_1._nativeDb].getFilePath()), this.STASHES_ROOT_DIR_NAME, `${db.briefcaseId}`);
+        if (ensureExists && !(0, node_fs_1.existsSync)(stashDir)) {
+            (0, node_fs_1.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 (!(0, node_fs_1.existsSync)(stashRoot)) {
+            throw new StashError("Invalid stash");
+        }
+        const stashFilePath = path.join(stashRoot, `${this.getStashId(args)}.stash`);
+        if (!(0, node_fs_1.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() === core_bentley_1.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, core_common_1.LockState.Shared, LockOrigin.Acquired);
+        await args.db.locks.acquireLocks({ shared });
+        const exclusive = this.queryLocks(args, core_common_1.LockState.Exclusive, LockOrigin.Acquired);
+        await args.db.locks.acquireLocks({ exclusive });
+        const newElements = this.queryLocks(args, core_common_1.LockState.Shared, LockOrigin.NewElement);
+        for (const id of newElements) {
+            if (!args.db.locks.holdsExclusiveLock(id)) {
+                args.db.locks[Symbols_1._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[Symbols_1._nativeDb].stashChanges({ stashRootDir, description: args.description, iModelId });
+        if (args.discardLocalChanges) {
+            await args.db.discardChanges({ retainLocks: args.retainLocks });
+        }
+        core_bentley_1.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) {
+            core_bentley_1.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() !== core_bentley_1.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 (!(0, node_fs_1.existsSync)(stashFile)) {
+            throw new StashError("Invalid stash");
+        }
+        const stashDb = new SQLiteDb_1.SQLiteDb();
+        stashDb.openDb(stashFile, core_bentley_1.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 (!(0, node_fs_1.existsSync)(stashDir)) {
+            return stashes;
+        }
+        (0, node_fs_1.readdirSync)(stashDir).filter((file) => {
+            const filePath = path.join(stashDir, file);
+            if ((0, node_fs_1.existsSync)(filePath) && (0, node_fs_1.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);
+            (0, node_fs_1.unlinkSync)(stashFile);
+            return true;
+        }
+        catch (error) {
+            core_bentley_1.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_1.IModelHost[Symbols_1._hubAccess].queryChangeset({
+            iModelId: args.stash.iModelId,
+            changeset: args.stash.parentChangeset,
+            accessToken: await IModelHost_1.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;
+        core_bentley_1.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
+            core_bentley_1.Logger.logWarning(loggerCategory, "Changeset ID mismatch");
+            const stashChangeset = await this.queryChangeset({ db, stash });
+            await BriefcaseManager_1.BriefcaseManager.pullAndApplyChangesets(db, { toIndex: stashChangeset.index });
+        }
+        db[Symbols_1._nativeDb].stashRestore(stashFile);
+        db[Symbols_1._resetIModelDb]();
+        db.saveChanges();
+        core_bentley_1.Logger.logInfo(loggerCategory, `Restored stash: ${this.getStashId(args)}`);
+    }
+}
+exports.StashManager = StashManager;
+//# sourceMappingURL=StashManager.js.map

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

package/lib/cjs/Texture.js.map

@@ -1 +1 @@
-{"version":3,"file":"Texture.js","sourceRoot":"","sources":["../../src/Texture.ts"],"names":[],"mappings":";AAAA;;;+FAG+F;AAC/F;;GAEG;;;AAGH,oDAE4B;AAC5B,uCAA8C;AAW9C;;GAEG;AACH,MAAa,OAAQ,SAAQ,2BAAiB;IAC5C,gBAAgB;IACT,MAAM,KAAc,SAAS,KAAa,OAAO,SAAS,CAAC,CAAC,CAAC;IAC7D,MAAM,CAAoB;IAC1B,IAAI,CAAa;IACjB,WAAW,CAAU;IAE5B,YAAY;IACZ,YAAsB,KAAyB,EAAE,MAAgB;QAC/D,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,iCAAmB,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;QACvG,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;IACvC,CAAC;IAEe,MAAM;QACpB,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,EAAkB,CAAC;QAC3C,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QACzB,GAAG,CAAC,IAAI,GAAG,iCAAmB,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzD,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACnC,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,UAAU,CAAC,MAAgB,EAAE,YAA4B,EAAE,IAAY;QACnF,MAAM,QAAQ,GAAa,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,yBAAW,CAAC,OAAO,CAAC,CAAC;QAC3E,OAAO,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,kBAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,kBAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACpH,CAAC;IAED;;;;;;;;;;OAUG;IACI,MAAM,CAAC,aAAa,CAAC,QAAkB,EAAE,iBAA6B,EAAE,IAAY,EAAE,MAAyB,EAAE,IAAsC,EAAE,WAAoB;QAClL,MAAM,YAAY,GAAuB;YACvC,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,iBAAiB,EAAE,IAAI,CAAC;YACxD,MAAM;YACN,IAAI;YACJ,WAAW;YACX,KAAK,EAAE,iBAAiB;YACxB,SAAS,EAAE,KAAK;SACjB,CAAC;QAEF,OAAO,IAAI,OAAO,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;;;;;OAUG;IACI,MAAM,CAAC,aAAa,CAAC,QAAkB,EAAE,iBAA6B,EAAE,IAAY,EAAE,MAAyB,EAAE,IAAsC,EAAE,WAAoB;QAClL,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;QACjG,OAAO,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3D,CAAC;CACF;AAzED,0BAyEC","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module Elements\n */\n\nimport { Id64String } from \"@itwin/core-bentley\";\nimport {\n  Base64EncodedString, BisCodeSpec, Code, CodeScopeProps, CodeSpec, ImageSourceFormat, TextureProps,\n} from \"@itwin/core-common\";\nimport { DefinitionElement } from \"./Element\";\nimport { IModelDb } from \"./IModelDb\";\n\n/** A [TextureProps]($common) in which the image data can be specified either as a base-64-encoded string or a Uint8Array.\n * @see [[Texture]] constructor.\n * @beta\n */\nexport interface TextureCreateProps extends Omit<TextureProps, \"data\"> {\n  data: Base64EncodedString | Uint8Array;\n}\n\n/** Defines a rendering texture that is associated with a Material and applied to surface geometry.\n * @public @preview\n */\nexport class Texture extends DefinitionElement {\n  /** @internal */\n  public static override get className(): string { return \"Texture\"; }\n  public format: ImageSourceFormat;\n  public data: Uint8Array;\n  public description?: string;\n\n  /** @beta */\n  protected constructor(props: TextureCreateProps, iModel: IModelDb) {\n    super(props, iModel);\n    this.format = props.format;\n    this.data = typeof props.data === \"string\" ? Base64EncodedString.toUint8Array(props.data) : props.data;\n    this.description = props.description;\n  }\n\n  public override toJSON(): TextureProps {\n    const val = super.toJSON() as TextureProps;\n    val.format = this.format;\n    val.data = Base64EncodedString.fromUint8Array(this.data);\n    val.description = this.description;\n    return val;\n  }\n\n  /** Create a Code for a Texture given a name that is meant to be unique within the scope of the specified DefinitionModel.\n   * @param iModel  The IModelDb\n   * @param scopeModelId The Id of the DefinitionModel that contains the Texture and provides the scope for its name.\n   * @param name The Texture name\n   */\n  public static createCode(iModel: IModelDb, scopeModelId: CodeScopeProps, name: string): Code {\n    const codeSpec: CodeSpec = iModel.codeSpecs.getByName(BisCodeSpec.texture);\n    return 0 === name.length ? Code.createEmpty() : new Code({ spec: codeSpec.id, scope: scopeModelId, value: name });\n  }\n\n  /** Create a texture with the given parameters.\n   * @param iModelDb The iModel to contain the texture.\n   * @param definitionModelId The [[DefinitionModel]] to contain the texture.\n   * @param name The name to serve as the texture's [Code]($common) value.\n   * @param format The format of the image data.\n   * @param data The image data in the format specified by `format`.\n   * @param description An optional description of the texture\n   * @returns The newly constructed Texture element.\n   * @throws [[IModelError]] if unable to create the element.\n   * @see [[insertTexture]] to insert a new texture into the iModel.\n   */\n  public static createTexture(iModelDb: IModelDb, definitionModelId: Id64String, name: string, format: ImageSourceFormat, data: Uint8Array | Base64EncodedString, description?: string): Texture {\n    const textureProps: TextureCreateProps = {\n      classFullName: this.classFullName,\n      code: this.createCode(iModelDb, definitionModelId, name),\n      format,\n      data,\n      description,\n      model: definitionModelId,\n      isPrivate: false,\n    };\n\n    return new Texture(textureProps, iModelDb);\n  }\n\n  /** Insert a new texture into a [[DefinitionModel]].\n   * @param iModelDb The iModel to contain the texture.\n   * @param definitionModelId The [[DefinitionModel]] to contain the texture.\n   * @param name The name to serve as the texture's [Code]($common) value.\n   * @param format The format of the image data.\n   * @param data The image data in the format specified by `format`.\n   * @param description An optional description of the texture\n   * @returns The Id of the newly-inserted texture element.\n   * @throws [[IModelError]] if unable to insert the element.\n   * @see [[insertTexture]] to insert a new texture into the iModel.\n   */\n  public static insertTexture(iModelDb: IModelDb, definitionModelId: Id64String, name: string, format: ImageSourceFormat, data: Uint8Array | Base64EncodedString, description?: string): Id64String {\n    const texture = this.createTexture(iModelDb, definitionModelId, name, format, data, description);\n    return iModelDb.elements.insertElement(texture.toJSON());\n  }\n}\n"]}
+{"version":3,"file":"Texture.js","sourceRoot":"","sources":["../../src/Texture.ts"],"names":[],"mappings":";AAAA;;;+FAG+F;AAC/F;;GAEG;;;AAGH,oDAE4B;AAC5B,uCAA8C;AAW9C;;GAEG;AACH,MAAa,OAAQ,SAAQ,2BAAiB;IAC5C,gBAAgB;IACT,MAAM,KAAc,SAAS,KAAa,OAAO,SAAS,CAAC,CAAC,CAAC;IAC7D,MAAM,CAAoB;IAC1B,IAAI,CAAa;IACjB,WAAW,CAAU;IAE5B,YAAY;IACZ,YAAsB,KAAyB,EAAE,MAAgB;QAC/D,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,iCAAmB,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;QACvG,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;IACvC,CAAC;IAEe,MAAM;QACpB,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,EAAkB,CAAC;QAC3C,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QACzB,GAAG,CAAC,IAAI,GAAG,iCAAmB,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzD,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACnC,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,UAAU,CAAC,MAAgB,EAAE,YAA4B,EAAE,IAAY;QACnF,MAAM,QAAQ,GAAa,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,yBAAW,CAAC,OAAO,CAAC,CAAC;QAC3E,OAAO,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,kBAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,kBAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACpH,CAAC;IAED;;;;;;;;;;OAUG;IACI,MAAM,CAAC,aAAa,CAAC,QAAkB,EAAE,iBAA6B,EAAE,IAAY,EAAE,MAAyB,EAAE,IAAsC,EAAE,WAAoB;QAClL,MAAM,YAAY,GAAuB;YACvC,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,iBAAiB,EAAE,IAAI,CAAC;YACxD,MAAM;YACN,IAAI;YACJ,WAAW;YACX,KAAK,EAAE,iBAAiB;YACxB,SAAS,EAAE,KAAK;SACjB,CAAC;QAEF,OAAO,IAAI,OAAO,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;;;;;OAUG;IACI,MAAM,CAAC,aAAa,CAAC,QAAkB,EAAE,iBAA6B,EAAE,IAAY,EAAE,MAAyB,EAAE,IAAsC,EAAE,WAAoB;QAClL,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;QACjG,OAAO,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3D,CAAC;CACF;AAzED,0BAyEC","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module Elements\r\n */\r\n\r\nimport { Id64String } from \"@itwin/core-bentley\";\r\nimport {\r\n  Base64EncodedString, BisCodeSpec, Code, CodeScopeProps, CodeSpec, ImageSourceFormat, TextureProps,\r\n} from \"@itwin/core-common\";\r\nimport { DefinitionElement } from \"./Element\";\r\nimport { IModelDb } from \"./IModelDb\";\r\n\r\n/** A [TextureProps]($common) in which the image data can be specified either as a base-64-encoded string or a Uint8Array.\r\n * @see [[Texture]] constructor.\r\n * @beta\r\n */\r\nexport interface TextureCreateProps extends Omit<TextureProps, \"data\"> {\r\n  data: Base64EncodedString | Uint8Array;\r\n}\r\n\r\n/** Defines a rendering texture that is associated with a Material and applied to surface geometry.\r\n * @public @preview\r\n */\r\nexport class Texture extends DefinitionElement {\r\n  /** @internal */\r\n  public static override get className(): string { return \"Texture\"; }\r\n  public format: ImageSourceFormat;\r\n  public data: Uint8Array;\r\n  public description?: string;\r\n\r\n  /** @beta */\r\n  protected constructor(props: TextureCreateProps, iModel: IModelDb) {\r\n    super(props, iModel);\r\n    this.format = props.format;\r\n    this.data = typeof props.data === \"string\" ? Base64EncodedString.toUint8Array(props.data) : props.data;\r\n    this.description = props.description;\r\n  }\r\n\r\n  public override toJSON(): TextureProps {\r\n    const val = super.toJSON() as TextureProps;\r\n    val.format = this.format;\r\n    val.data = Base64EncodedString.fromUint8Array(this.data);\r\n    val.description = this.description;\r\n    return val;\r\n  }\r\n\r\n  /** Create a Code for a Texture given a name that is meant to be unique within the scope of the specified DefinitionModel.\r\n   * @param iModel  The IModelDb\r\n   * @param scopeModelId The Id of the DefinitionModel that contains the Texture and provides the scope for its name.\r\n   * @param name The Texture name\r\n   */\r\n  public static createCode(iModel: IModelDb, scopeModelId: CodeScopeProps, name: string): Code {\r\n    const codeSpec: CodeSpec = iModel.codeSpecs.getByName(BisCodeSpec.texture);\r\n    return 0 === name.length ? Code.createEmpty() : new Code({ spec: codeSpec.id, scope: scopeModelId, value: name });\r\n  }\r\n\r\n  /** Create a texture with the given parameters.\r\n   * @param iModelDb The iModel to contain the texture.\r\n   * @param definitionModelId The [[DefinitionModel]] to contain the texture.\r\n   * @param name The name to serve as the texture's [Code]($common) value.\r\n   * @param format The format of the image data.\r\n   * @param data The image data in the format specified by `format`.\r\n   * @param description An optional description of the texture\r\n   * @returns The newly constructed Texture element.\r\n   * @throws [[IModelError]] if unable to create the element.\r\n   * @see [[insertTexture]] to insert a new texture into the iModel.\r\n   */\r\n  public static createTexture(iModelDb: IModelDb, definitionModelId: Id64String, name: string, format: ImageSourceFormat, data: Uint8Array | Base64EncodedString, description?: string): Texture {\r\n    const textureProps: TextureCreateProps = {\r\n      classFullName: this.classFullName,\r\n      code: this.createCode(iModelDb, definitionModelId, name),\r\n      format,\r\n      data,\r\n      description,\r\n      model: definitionModelId,\r\n      isPrivate: false,\r\n    };\r\n\r\n    return new Texture(textureProps, iModelDb);\r\n  }\r\n\r\n  /** Insert a new texture into a [[DefinitionModel]].\r\n   * @param iModelDb The iModel to contain the texture.\r\n   * @param definitionModelId The [[DefinitionModel]] to contain the texture.\r\n   * @param name The name to serve as the texture's [Code]($common) value.\r\n   * @param format The format of the image data.\r\n   * @param data The image data in the format specified by `format`.\r\n   * @param description An optional description of the texture\r\n   * @returns The Id of the newly-inserted texture element.\r\n   * @throws [[IModelError]] if unable to insert the element.\r\n   * @see [[insertTexture]] to insert a new texture into the iModel.\r\n   */\r\n  public static insertTexture(iModelDb: IModelDb, definitionModelId: Id64String, name: string, format: ImageSourceFormat, data: Uint8Array | Base64EncodedString, description?: string): Id64String {\r\n    const texture = this.createTexture(iModelDb, definitionModelId, name, format, data, description);\r\n    return iModelDb.elements.insertElement(texture.toJSON());\r\n  }\r\n}\r\n"]}

package/lib/cjs/TileStorage.js.map

@@ -1 +1 @@
-{"version":3,"file":"TileStorage.js","sourceRoot":"","sources":["../../src/TileStorage.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\nimport { gunzip, gzip } from \"zlib\";\nimport { promisify } from \"util\";\nimport { Metadata, ObjectReference, ServerStorage, TransferConfig } from \"@itwin/object-storage-core\";\nimport { getTileObjectReference } from \"@itwin/core-common\";\nimport { Logger } from \"@itwin/core-bentley\";\nimport { BackendLoggerCategory } from \"./BackendLoggerCategory\";\nimport { IModelHost } from \"./IModelHost\";\n\n/**\n * Identifies a tile in cloud tile cache.\n * @beta\n */\nexport interface TileId {\n  treeId: string;\n  contentId: string;\n  guid: string;\n}\n\n/**\n * Facilitates interaction with cloud tile cache.\n * @beta\n */\nexport class TileStorage {\n  /**\n   * Allows using the underlying `ServerStorage` API directly.\n   * @see https://github.com/iTwin/object-storage/\n   */\n  public readonly storage: ServerStorage;\n\n  public constructor(storage: ServerStorage) {\n    this.storage = storage;\n  }\n\n  private _initializedIModels: Set<string> = new Set();\n\n  /**\n   * Ensures any required cloud storage resources for a specific iModel are ready to use.\n   */\n  public async initialize(iModelId: string): Promise<void> {\n    if (this._initializedIModels.has(iModelId))\n      return;\n    if (!(await this.storage.baseDirectoryExists({ baseDirectory: iModelId }))) {\n      try {\n        await this.storage.createBaseDirectory({ baseDirectory: iModelId });\n      } catch (e: any) {\n        // Ignore 409 errors. This is what Azure blob storage returns when the container already exists.\n        // Usually this means multiple backends tried to initialize tile storage at the same time.\n        if(e.statusCode !== 409)\n          throw e;\n      }\n    }\n    this._initializedIModels.add(iModelId);\n  }\n\n  /**\n   * Returns config that can be used by frontends to download tiles\n   * @param iModelId Id of the iModel\n   * @param expiresInSeconds Optional number of seconds until the download URL expires. Defaults to expiring exactly at midnight of next Sunday to enable persistent client-side caching.\n   *  It is recommended to set this to a shorter period when using S3-compatible storage - an exact expiry date cannot be ensured due to limitations in their API.\n   * @see [TileStorage]($frontend)\n   */\n  public async getDownloadConfig(iModelId: string, expiresInSeconds?: number): Promise<TransferConfig> {\n    try {\n      if (expiresInSeconds !== undefined)\n        return await this.storage.getDownloadConfig({ baseDirectory: iModelId }, { expiresInSeconds });\n      const expiresOn = new Date();\n      expiresOn.setDate(expiresOn.getDate() + (7 - expiresOn.getDay())); // next Sunday\n      expiresOn.setHours(0, 0, 0, 0); // exactly at midnight\n      return await this.storage.getDownloadConfig({ baseDirectory: iModelId }, { expiresOn });\n    } catch (err) {\n      this.logException(\"Failed to get download config\", err);\n      throw err;\n    }\n  }\n\n  /**\n   * Uploads a tile to the cloud cache.\n   */\n  public async uploadTile(iModelId: string, changesetId: string, treeId: string, contentId: string, content: Uint8Array, guid?: string, metadata?: Metadata): Promise<void> {\n    try {\n      await this.storage.upload(\n        getTileObjectReference(iModelId, changesetId, treeId, contentId, guid),\n        Buffer.from(IModelHost.compressCachedTiles ? await promisify(gzip)(content.buffer) : content.buffer),\n        metadata,\n        IModelHost.compressCachedTiles ? { contentEncoding: \"gzip\" } : undefined,\n      );\n    } catch (err) {\n      this.logException(\"Failed to upload tile\", err);\n      throw err;\n    }\n  }\n\n  /**\n   * Downloads a tile from the cloud cache.\n   */\n  public async downloadTile(iModelId: string, changesetId: string, treeId: string, contentId: string, guid?: string): Promise<Uint8Array> {\n    try {\n      const buffer = await this.storage.download(\n        getTileObjectReference(iModelId, changesetId, treeId, contentId, guid),\n        \"buffer\",\n      );\n      return IModelHost.compressCachedTiles ? await promisify(gunzip)(buffer) : buffer;\n    } catch (err) {\n      this.logException(\"Failed to download tile\", err);\n      throw err;\n    }\n  }\n\n  /**\n   * Returns an async iterator of all tiles that are found in the cloud cache.\n   */\n  public async *getCachedTilesGenerator(iModelId: string): AsyncGenerator<TileId> {\n    const iterator = this.getCachedTilePages(iModelId);\n    for await (const page of iterator) {\n      for (const tile of page) {\n        yield tile;\n      }\n    }\n  }\n\n  private async *getCachedTilePages(iModelId: string): AsyncGenerator<TileId[]> {\n    const iterator = this.storage.getListObjectsPagedIterator({ baseDirectory: iModelId }, 500);\n    let prevPage: IteratorResult<ObjectReference[], any> | undefined;\n    do {\n      // initiate loading the next page\n      const page = iterator.next();\n      // process results from the previous page\n      if (prevPage)\n        yield this.convertPage(prevPage.value);\n      // finish loading the next page\n      prevPage = await page;\n    } while (!prevPage.done);\n  }\n\n  private convertPage(page: ObjectReference[]): TileId[] {\n    return page\n      .map((objectReference) => ({\n        parts: objectReference.relativeDirectory?.split(\"/\") ?? [\"\"],\n        objectName: objectReference.objectName,\n      }))\n      .filter(({ parts, objectName }) => {\n        if (parts[0] !== \"tiles\")\n          return false;\n        if (parts.length !== 3) {\n          Logger.logWarning(BackendLoggerCategory.IModelTileStorage, \"Malformed tile id found in tile cache: {tileId}\", { tileId: [...parts, objectName].join(\"/\") });\n          return false;\n        }\n        return true;\n      }).map(({ parts, objectName }) => {\n        // relativeDirectory = tiles/<treeId>/<guid>\n        // objectName = <contentId>\n        return {\n          treeId: parts[1],\n          contentId: objectName,\n          guid: parts[2],\n        };\n      });\n  }\n\n  /**\n   * Returns a list of all tiles that are found in the cloud cache.\n   */\n  public async getCachedTiles(iModelId: string): Promise<TileId[]> {\n    const results: TileId[] = [];\n    for await (const page of this.getCachedTilePages(iModelId)) {\n      results.push(...page);\n    }\n    return results;\n  }\n\n  /**\n   * Returns a boolean indicating whether a tile exists in the cloud cache\n   */\n  public async isTileCached(iModelId: string, changesetId: string, treeId: string, contentId: string, guid?: string): Promise<boolean> {\n    return this.storage.objectExists(getTileObjectReference(iModelId, changesetId, treeId, contentId, guid));\n  }\n\n  private logException(message: string, err: unknown): void {\n    Logger.logException(\n      BackendLoggerCategory.IModelTileStorage,\n      err,\n      (category, msg, errorMetadata) => Logger.logError(category, `${message}: {errorMessage}`, { ...errorMetadata, errorMessage: msg }),\n    );\n  }\n}\n"]}
+{"version":3,"file":"TileStorage.js","sourceRoot":"","sources":["../../src/TileStorage.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\nimport { gunzip, gzip } from \"zlib\";\r\nimport { promisify } from \"util\";\r\nimport { Metadata, ObjectReference, ServerStorage, TransferConfig } from \"@itwin/object-storage-core\";\r\nimport { getTileObjectReference } from \"@itwin/core-common\";\r\nimport { Logger } from \"@itwin/core-bentley\";\r\nimport { BackendLoggerCategory } from \"./BackendLoggerCategory\";\r\nimport { IModelHost } from \"./IModelHost\";\r\n\r\n/**\r\n * Identifies a tile in cloud tile cache.\r\n * @beta\r\n */\r\nexport interface TileId {\r\n  treeId: string;\r\n  contentId: string;\r\n  guid: string;\r\n}\r\n\r\n/**\r\n * Facilitates interaction with cloud tile cache.\r\n * @beta\r\n */\r\nexport class TileStorage {\r\n  /**\r\n   * Allows using the underlying `ServerStorage` API directly.\r\n   * @see https://github.com/iTwin/object-storage/\r\n   */\r\n  public readonly storage: ServerStorage;\r\n\r\n  public constructor(storage: ServerStorage) {\r\n    this.storage = storage;\r\n  }\r\n\r\n  private _initializedIModels: Set<string> = new Set();\r\n\r\n  /**\r\n   * Ensures any required cloud storage resources for a specific iModel are ready to use.\r\n   */\r\n  public async initialize(iModelId: string): Promise<void> {\r\n    if (this._initializedIModels.has(iModelId))\r\n      return;\r\n    if (!(await this.storage.baseDirectoryExists({ baseDirectory: iModelId }))) {\r\n      try {\r\n        await this.storage.createBaseDirectory({ baseDirectory: iModelId });\r\n      } catch (e: any) {\r\n        // Ignore 409 errors. This is what Azure blob storage returns when the container already exists.\r\n        // Usually this means multiple backends tried to initialize tile storage at the same time.\r\n        if(e.statusCode !== 409)\r\n          throw e;\r\n      }\r\n    }\r\n    this._initializedIModels.add(iModelId);\r\n  }\r\n\r\n  /**\r\n   * Returns config that can be used by frontends to download tiles\r\n   * @param iModelId Id of the iModel\r\n   * @param expiresInSeconds Optional number of seconds until the download URL expires. Defaults to expiring exactly at midnight of next Sunday to enable persistent client-side caching.\r\n   *  It is recommended to set this to a shorter period when using S3-compatible storage - an exact expiry date cannot be ensured due to limitations in their API.\r\n   * @see [TileStorage]($frontend)\r\n   */\r\n  public async getDownloadConfig(iModelId: string, expiresInSeconds?: number): Promise<TransferConfig> {\r\n    try {\r\n      if (expiresInSeconds !== undefined)\r\n        return await this.storage.getDownloadConfig({ baseDirectory: iModelId }, { expiresInSeconds });\r\n      const expiresOn = new Date();\r\n      expiresOn.setDate(expiresOn.getDate() + (7 - expiresOn.getDay())); // next Sunday\r\n      expiresOn.setHours(0, 0, 0, 0); // exactly at midnight\r\n      return await this.storage.getDownloadConfig({ baseDirectory: iModelId }, { expiresOn });\r\n    } catch (err) {\r\n      this.logException(\"Failed to get download config\", err);\r\n      throw err;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Uploads a tile to the cloud cache.\r\n   */\r\n  public async uploadTile(iModelId: string, changesetId: string, treeId: string, contentId: string, content: Uint8Array, guid?: string, metadata?: Metadata): Promise<void> {\r\n    try {\r\n      await this.storage.upload(\r\n        getTileObjectReference(iModelId, changesetId, treeId, contentId, guid),\r\n        Buffer.from(IModelHost.compressCachedTiles ? await promisify(gzip)(content.buffer) : content.buffer),\r\n        metadata,\r\n        IModelHost.compressCachedTiles ? { contentEncoding: \"gzip\" } : undefined,\r\n      );\r\n    } catch (err) {\r\n      this.logException(\"Failed to upload tile\", err);\r\n      throw err;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Downloads a tile from the cloud cache.\r\n   */\r\n  public async downloadTile(iModelId: string, changesetId: string, treeId: string, contentId: string, guid?: string): Promise<Uint8Array> {\r\n    try {\r\n      const buffer = await this.storage.download(\r\n        getTileObjectReference(iModelId, changesetId, treeId, contentId, guid),\r\n        \"buffer\",\r\n      );\r\n      return IModelHost.compressCachedTiles ? await promisify(gunzip)(buffer) : buffer;\r\n    } catch (err) {\r\n      this.logException(\"Failed to download tile\", err);\r\n      throw err;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Returns an async iterator of all tiles that are found in the cloud cache.\r\n   */\r\n  public async *getCachedTilesGenerator(iModelId: string): AsyncGenerator<TileId> {\r\n    const iterator = this.getCachedTilePages(iModelId);\r\n    for await (const page of iterator) {\r\n      for (const tile of page) {\r\n        yield tile;\r\n      }\r\n    }\r\n  }\r\n\r\n  private async *getCachedTilePages(iModelId: string): AsyncGenerator<TileId[]> {\r\n    const iterator = this.storage.getListObjectsPagedIterator({ baseDirectory: iModelId }, 500);\r\n    let prevPage: IteratorResult<ObjectReference[], any> | undefined;\r\n    do {\r\n      // initiate loading the next page\r\n      const page = iterator.next();\r\n      // process results from the previous page\r\n      if (prevPage)\r\n        yield this.convertPage(prevPage.value);\r\n      // finish loading the next page\r\n      prevPage = await page;\r\n    } while (!prevPage.done);\r\n  }\r\n\r\n  private convertPage(page: ObjectReference[]): TileId[] {\r\n    return page\r\n      .map((objectReference) => ({\r\n        parts: objectReference.relativeDirectory?.split(\"/\") ?? [\"\"],\r\n        objectName: objectReference.objectName,\r\n      }))\r\n      .filter(({ parts, objectName }) => {\r\n        if (parts[0] !== \"tiles\")\r\n          return false;\r\n        if (parts.length !== 3) {\r\n          Logger.logWarning(BackendLoggerCategory.IModelTileStorage, \"Malformed tile id found in tile cache: {tileId}\", { tileId: [...parts, objectName].join(\"/\") });\r\n          return false;\r\n        }\r\n        return true;\r\n      }).map(({ parts, objectName }) => {\r\n        // relativeDirectory = tiles/<treeId>/<guid>\r\n        // objectName = <contentId>\r\n        return {\r\n          treeId: parts[1],\r\n          contentId: objectName,\r\n          guid: parts[2],\r\n        };\r\n      });\r\n  }\r\n\r\n  /**\r\n   * Returns a list of all tiles that are found in the cloud cache.\r\n   */\r\n  public async getCachedTiles(iModelId: string): Promise<TileId[]> {\r\n    const results: TileId[] = [];\r\n    for await (const page of this.getCachedTilePages(iModelId)) {\r\n      results.push(...page);\r\n    }\r\n    return results;\r\n  }\r\n\r\n  /**\r\n   * Returns a boolean indicating whether a tile exists in the cloud cache\r\n   */\r\n  public async isTileCached(iModelId: string, changesetId: string, treeId: string, contentId: string, guid?: string): Promise<boolean> {\r\n    return this.storage.objectExists(getTileObjectReference(iModelId, changesetId, treeId, contentId, guid));\r\n  }\r\n\r\n  private logException(message: string, err: unknown): void {\r\n    Logger.logException(\r\n      BackendLoggerCategory.IModelTileStorage,\r\n      err,\r\n      (category, msg, errorMetadata) => Logger.logError(category, `${message}: {errorMessage}`, { ...errorMetadata, errorMessage: msg }),\r\n    );\r\n  }\r\n}\r\n"]}