@itwin/core-backend 5.6.0-dev.1 → 5.6.0-dev.10

package/lib/cjs/IModelDb.js

@@ -7,7 +7,7 @@
  * @module iModels
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StandaloneDb = exports.SnapshotDb = exports.BriefcaseDb = exports.IModelDb = exports.BriefcaseLocalValue = void 0;
+exports.StandaloneDb = exports.SnapshotDb = exports.BriefcaseDb = exports.IModelDb = exports.DataTransformationStrategy = exports.BriefcaseLocalValue = void 0;
 const fs = require("fs");
 const path_1 = require("path");
 const touch = require("touch");
@@ -84,6 +84,24 @@ class IModelSettings extends SettingsImpl_1.SettingsImpl {
         yield* IModelHost_1.IModelHost.appWorkspace.settings.getSettingEntries(name);
     }
 }
+/**
+ * Strategy for transforming data during schema import.
+ * @beta
+ */
+var DataTransformationStrategy;
+(function (DataTransformationStrategy) {
+    /** No data transformation will be performed after schema import. */
+    DataTransformationStrategy["None"] = "None";
+    /** Data transformation will be performed using a temporary snapshot created before schema import.
+     *  Useful for complex transformations requiring full read access to complete pre-import state for lazy conversion.
+     *  Note: Creates a complete copy of the briefcase file, which may be large.
+     */
+    DataTransformationStrategy["Snapshot"] = "Snapshot";
+    /** Data transformation will be performed using in-memory cached data created before schema import.
+     *  Useful for lightweight transformations involving limited data.
+     */
+    DataTransformationStrategy["InMemory"] = "InMemory";
+})(DataTransformationStrategy || (exports.DataTransformationStrategy = DataTransformationStrategy = {}));
 /** An iModel database file. The database file can either be a briefcase or a snapshot.
  * @see [Accessing iModels]($docs/learning/backend/AccessingIModels.md)
  * @see [About IModelDb]($docs/learning/backend/IModelDb.md)
@@ -238,11 +256,8 @@ class IModelDb extends core_common_1.IModel {
      * @note There are some reserve tablespace names that cannot be used. They are 'main', 'schema_sync_db', 'ecchange' & 'temp'
      * @param fileName IModel file name
      * @param alias identifier for the attached file. This identifier is used to access schema from the attached file. e.g. if alias is 'abc' then schema can be accessed using 'abc.MySchema.MyClass'
-     *
-     * *Example:*
-     * ``` ts
-     *  [[include:IModelDb_attachDb.code]]
-     * ```
+     * @example
+     * [[include:IModelDb_attachDb.code]]
      */
     attachDb(fileName, alias) {
         if (alias.toLowerCase() === "main" || alias.toLowerCase() === "schema_sync_db" || alias.toLowerCase() === "ecchange" || alias.toLowerCase() === "temp") {
@@ -255,10 +270,8 @@ class IModelDb extends core_common_1.IModel {
      * @note There are some reserve tablespace names that cannot be used. They are 'main', 'schema_sync_db', 'ecchange' & 'temp'
      * @param alias identifer that was used in the call to [[attachDb]]
      *
-     * *Example:*
-     * ``` ts
-     *  [[include:IModelDb_attachDb.code]]
-     * ```
+     * @example [[include:IModelDb_attachDb.code]]
+     *
      */
     detachDb(alias) {
         if (alias.toLowerCase() === "main" || alias.toLowerCase() === "schema_sync_db" || alias.toLowerCase() === "ecchange" || alias.toLowerCase() === "temp") {
@@ -267,11 +280,15 @@ class IModelDb extends core_common_1.IModel {
         this.clearCaches();
         this[Symbols_1._nativeDb].detachDb(alias);
     }
-    /** Close this IModel, if it is currently open, and save changes if it was opened in ReadWrite mode. */
-    close() {
+    /** Close this IModel, if it is currently open, and save changes if it was opened in ReadWrite mode.
+     * @param options Options for closing the iModel.
+     */
+    close(options) {
         if (!this.isOpen)
             return; // don't continue if already closed
         this.beforeClose();
+        if (options?.optimize)
+            this.optimize();
         IModelDb._openDbs.delete(this._fileKey);
         this._workspace?.close();
         this.locks[Symbols_1._close]();
@@ -282,6 +299,40 @@ class IModelDb extends core_common_1.IModel {
             this.saveChanges();
         this[Symbols_1._nativeDb].closeFile();
     }
+    /** Optimize this iModel by vacuuming, and analyzing.
+     *
+     * @note This operation requires exclusive access to the database and may take some time on large files.
+     * @beta
+     */
+    optimize() {
+        // Vacuum to reclaim space and defragment
+        this.vacuum();
+        // Analyze to update statistics for query optimizer
+        this.analyze();
+    }
+    /**
+     * Vacuum the model to reclaim space and defragment.
+     * @throws [[IModelError]] if the iModel is not open or is read-only.
+     * @beta
+     */
+    vacuum() {
+        if (!this.isOpen || this.isReadonly)
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "IModel is not open or is read-only");
+        this[Symbols_1._nativeDb].clearECDbCache();
+        this[Symbols_1._nativeDb].vacuum();
+    }
+    /**
+     * Update SQLite query optimizer statistics for this iModel.
+     * This helps SQLite choose better query plans.
+     *
+     * @throws [[IModelError]] if the iModel is not open or is read-only.
+     * @beta
+     */
+    analyze() {
+        if (!this.isOpen || this.isReadonly)
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "IModel is not open or is read-only");
+        this[Symbols_1._nativeDb].analyze();
+    }
     /** @internal */
     async refreshContainerForRpc(_userAccessToken) { }
     /** Event called when the iModel is about to be closed. */
@@ -723,21 +774,68 @@ class IModelDb extends core_common_1.IModel {
             this.clearCaches();
         }
     }
-    /** Import an ECSchema. On success, the schema definition is stored in the iModel.
-     * This method is asynchronous (must be awaited) because, in the case where this IModelDb is a briefcase, this method first obtains the schema lock from the iModel server.
-     * You must import a schema into an iModel before you can insert instances of the classes in that schema. See [[Element]]
-     * @param schemaFileName  array of Full paths to ECSchema.xml files to be imported.
-     * @param {SchemaImportOptions} options - options during schema import.
-     * @throws [[IModelError]] if the schema lock cannot be obtained or there is a problem importing the schema.
-     * @note Changes are saved if importSchemas is successful and abandoned if not successful.
-     * - You can use NativeLoggerCategory to turn on the native logs. You can also control [what exactly is logged by the loggers](https://www.itwinjs.org/learning/common/logging/#controlling-what-is-logged).
-     * - See [Schema Versioning]($docs/bis/guide/schema-evolution/schema-versioning-and-generations.md) for more information on acceptable changes to schemas.
-     * @note This method should not be called from {TxnManager.withIndirectTxnModeAsync} or {RebaseHandler.recompute}.
-    * @see querySchemaVersion
+    /** Helper to clean up snapshot resources safely
+     * @internal
      */
-    async importSchemas(schemaFileNames, options) {
-        if (schemaFileNames.length === 0)
-            return;
+    cleanupSnapshot(resources) {
+        if (resources.snapshot) {
+            const pathName = resources.snapshot.pathName;
+            resources.snapshot.close();
+            if (pathName && IModelJsFs_1.IModelJsFs.existsSync(pathName)) {
+                IModelJsFs_1.IModelJsFs.removeSync(pathName);
+            }
+        }
+    }
+    async preSchemaImportCallback(callback, context) {
+        const callbackResources = {
+            transformStrategy: DataTransformationStrategy.None,
+        };
+        try {
+            if (callback?.preSchemaImportCallback) {
+                const callbackResult = await callback.preSchemaImportCallback(context);
+                callbackResources.transformStrategy = callbackResult.transformStrategy;
+                if (callbackResult.transformStrategy === DataTransformationStrategy.Snapshot) {
+                    // Create temporary snapshot file
+                    const snapshotDb = SnapshotDb.createFrom(this, `${this.pathName}.snapshot-${Date.now()}`);
+                    callbackResources.snapshot = snapshotDb;
+                }
+                else if (callbackResult.transformStrategy === DataTransformationStrategy.InMemory) {
+                    if (callbackResult.cachedData === undefined) {
+                        throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "InMemory transform strategy requires cachedData to be provided.");
+                    }
+                    callbackResources.cachedData = callbackResult.cachedData;
+                }
+            }
+        }
+        catch (callbackError) {
+            this.abandonChanges();
+            this.cleanupSnapshot(callbackResources);
+            throw new core_common_1.IModelError(callbackError.errorNumber ?? core_bentley_1.IModelStatus.BadRequest, `Failed to execute preSchemaImportCallback: ${callbackError.message}`);
+        }
+        return callbackResources;
+    }
+    async postSchemaImportCallback(callback, context) {
+        if (context.resources.transformStrategy === DataTransformationStrategy.Snapshot && (context.resources.snapshot === undefined || !IModelJsFs_1.IModelJsFs.existsSync(context.resources.snapshot.pathName))) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Snapshot transform strategy requires a snapshot to be created");
+        }
+        if (context.resources.transformStrategy === DataTransformationStrategy.InMemory && context.resources.cachedData === undefined) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "InMemory transform strategy requires cachedData to be provided.");
+        }
+        try {
+            if (callback?.postSchemaImportCallback)
+                await callback.postSchemaImportCallback(context);
+        }
+        catch (callbackError) {
+            this.abandonChanges();
+            throw new core_common_1.IModelError(callbackError.errorNumber ?? core_bentley_1.IModelStatus.BadRequest, `Failed to execute postSchemaImportCallback: ${callbackError.message}`);
+        }
+        finally {
+            // Always clean up snapshot, whether success or error
+            this.cleanupSnapshot(context.resources);
+        }
+    }
+    /** Shared implementation for importing schemas from file or string. */
+    async importSchemasInternal(schemas, options, nativeImportOp) {
         if (this instanceof BriefcaseDb) {
             if (this.txns.rebaser.isRebasing) {
                 throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Cannot import schemas while rebasing");
@@ -746,13 +844,25 @@ class IModelDb extends core_common_1.IModel {
                 throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Cannot import schemas while in an indirect change scope");
             }
         }
+        if (options?.channelUpgrade) {
+            try {
+                await this.channels.upgradeChannel(options.channelUpgrade, this, options.data);
+            }
+            catch (error) {
+                this.abandonChanges();
+                throw error;
+            }
+        }
+        let preSchemaImportCallbackResult = { transformStrategy: DataTransformationStrategy.None };
+        if (options?.schemaImportCallbacks?.preSchemaImportCallback)
+            preSchemaImportCallbackResult = await this.preSchemaImportCallback(options.schemaImportCallbacks, { iModel: this, data: options.data, schemaData: schemas });
         const maybeCustomNativeContext = options?.ecSchemaXmlContext?.nativeContext;
         if (this[Symbols_1._nativeDb].schemaSyncEnabled()) {
             await SchemaSync_1.SchemaSync.withLockedAccess(this, { openMode: core_bentley_1.OpenMode.Readonly, operationName: "schema sync" }, async (syncAccess) => {
                 const schemaSyncDbUri = syncAccess.getUri();
                 this.saveChanges();
                 try {
-                    this[Symbols_1._nativeDb].importSchemas(schemaFileNames, { schemaLockHeld: false, ecSchemaXmlContext: maybeCustomNativeContext, schemaSyncDbUri });
+                    nativeImportOp(schemas, { schemaLockHeld: false, ecSchemaXmlContext: maybeCustomNativeContext, schemaSyncDbUri });
                 }
                 catch (outerErr) {
                     if (core_bentley_1.DbResult.BE_SQLITE_ERROR_DataTransformRequired === outerErr.errorNumber) {
@@ -760,7 +870,7 @@ class IModelDb extends core_common_1.IModel {
                         if (this[Symbols_1._nativeDb].getITwinId() !== core_bentley_1.Guid.empty)
                             await this.acquireSchemaLock();
                         try {
-                            this[Symbols_1._nativeDb].importSchemas(schemaFileNames, { schemaLockHeld: true, ecSchemaXmlContext: maybeCustomNativeContext, schemaSyncDbUri });
+                            nativeImportOp(schemas, { schemaLockHeld: true, ecSchemaXmlContext: maybeCustomNativeContext, schemaSyncDbUri });
                         }
                         catch (innerErr) {
                             throw new core_common_1.IModelError(innerErr.errorNumber, innerErr.message);
@@ -780,71 +890,48 @@ class IModelDb extends core_common_1.IModel {
             if (this[Symbols_1._nativeDb].getITwinId() !== core_bentley_1.Guid.empty) // if this iModel is associated with an iTwin, importing schema requires the schema lock
                 await this.acquireSchemaLock();
             try {
-                this[Symbols_1._nativeDb].importSchemas(schemaFileNames, nativeImportOptions);
+                nativeImportOp(schemas, nativeImportOptions);
             }
             catch (err) {
                 throw new core_common_1.IModelError(err.errorNumber, err.message);
             }
         }
         this.clearCaches();
+        if (options?.schemaImportCallbacks?.postSchemaImportCallback)
+            await this.postSchemaImportCallback(options.schemaImportCallbacks, { iModel: this, resources: preSchemaImportCallbackResult, data: options.data });
+    }
+    /** Import an ECSchema. On success, the schema definition is stored in the iModel.
+     * This method is asynchronous (must be awaited) because, in the case where this IModelDb is a briefcase, this method first obtains the schema lock from the iModel server.
+     * You must import a schema into an iModel before you can insert instances of the classes in that schema. See [[Element]]
+     * @param schemaFileName  array of Full paths to ECSchema.xml files to be imported.
+     * @param {SchemaImportOptions} options - options during schema import.
+     * @throws [[IModelError]] if the schema lock cannot be obtained or there is a problem importing the schema.
+     * @note Changes are saved if importSchemas is successful and abandoned if not successful.
+     * - You can use NativeLoggerCategory to turn on the native logs. You can also control [what exactly is logged by the loggers](https://www.itwinjs.org/learning/common/logging/#controlling-what-is-logged).
+     * - See [Schema Versioning]($docs/bis/guide/schema-evolution/schema-versioning-and-generations.md) for more information on acceptable changes to schemas.
+     * @note This method should not be called from {TxnManager.withIndirectTxnModeAsync} or {RebaseHandler.recompute}.
+     * @see querySchemaVersion
+     */
+    async importSchemas(schemaFileNames, options) {
+        if (schemaFileNames.length === 0)
+            return;
+        await this.importSchemasInternal(schemaFileNames, options, (schemas, importOptions) => this[Symbols_1._nativeDb].importSchemas(schemas, importOptions));
     }
     /** Import ECSchema(s) serialized to XML. On success, the schema definition is stored in the iModel.
      * This method is asynchronous (must be awaited) because, in the case where this IModelDb is a briefcase, this method first obtains the schema lock from the iModel server.
      * You must import a schema into an iModel before you can insert instances of the classes in that schema. See [[Element]]
      * @param serializedXmlSchemas  The xml string(s) created from a serialized ECSchema.
+     * @param {SchemaImportOptions} options - options during schema import.
      * @throws [[IModelError]] if the schema lock cannot be obtained or there is a problem importing the schema.
      * @note Changes are saved if importSchemaStrings is successful and abandoned if not successful.
      * @note This method should not be called from {TxnManager.withIndirectTxnModeAsync} or {RebaseHandler.recompute}.
      * @see querySchemaVersion
      * @alpha
      */
-    async importSchemaStrings(serializedXmlSchemas) {
+    async importSchemaStrings(serializedXmlSchemas, options) {
         if (serializedXmlSchemas.length === 0)
             return;
-        if (this instanceof BriefcaseDb) {
-            if (this.txns.rebaser.isRebasing) {
-                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Cannot import schemas while rebasing");
-            }
-            if (this.txns.isIndirectChanges) {
-                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Cannot import schemas while in an indirect change scope");
-            }
-        }
-        if (this[Symbols_1._nativeDb].schemaSyncEnabled()) {
-            await SchemaSync_1.SchemaSync.withLockedAccess(this, { openMode: core_bentley_1.OpenMode.Readonly, operationName: "schemaSync" }, async (syncAccess) => {
-                const schemaSyncDbUri = syncAccess.getUri();
-                this.saveChanges();
-                try {
-                    this[Symbols_1._nativeDb].importXmlSchemas(serializedXmlSchemas, { schemaLockHeld: false, schemaSyncDbUri });
-                }
-                catch (outerErr) {
-                    if (core_bentley_1.DbResult.BE_SQLITE_ERROR_DataTransformRequired === outerErr.errorNumber) {
-                        this.abandonChanges();
-                        if (this[Symbols_1._nativeDb].getITwinId() !== core_bentley_1.Guid.empty)
-                            await this.acquireSchemaLock();
-                        try {
-                            this[Symbols_1._nativeDb].importXmlSchemas(serializedXmlSchemas, { schemaLockHeld: true, schemaSyncDbUri });
-                        }
-                        catch (innerErr) {
-                            throw new core_common_1.IModelError(innerErr.errorNumber, innerErr.message);
-                        }
-                    }
-                    else {
-                        throw new core_common_1.IModelError(outerErr.errorNumber, outerErr.message);
-                    }
-                }
-            });
-        }
-        else {
-            if (this.iTwinId && this.iTwinId !== core_bentley_1.Guid.empty) // if this iModel is associated with an iTwin, importing schema requires the schema lock
-                await this.acquireSchemaLock();
-            try {
-                this[Symbols_1._nativeDb].importXmlSchemas(serializedXmlSchemas, { schemaLockHeld: true });
-            }
-            catch (err) {
-                throw new core_common_1.IModelError(err.errorNumber, err.message);
-            }
-        }
-        this.clearCaches();
+        await this.importSchemasInternal(serializedXmlSchemas, options, (schemas, importOptions) => this[Symbols_1._nativeDb].importXmlSchemas(schemas, importOptions));
     }
     /** Find an opened instance of any subclass of IModelDb, by filename
      * @note this method returns an IModelDb if the filename is open for *any* subclass of IModelDb
@@ -3214,11 +3301,11 @@ class BriefcaseDb extends IModelDb {
         });
         this.txns._onChangesPushed(this.changeset);
     }
-    close() {
+    close(options) {
         if (this.isBriefcase && this.isOpen && !this.isReadonly && this.txns.rebaser.inProgress()) {
             this.abandonChanges();
         }
-        super.close();
+        super.close(options);
         this.onClosed.raiseEvent();
     }
 }