@itwin/imodel-transformer 2.0.0-dev.7 → 2.0.0-dev.71

package/lib/cjs/IModelImporter.js

@@ -13,10 +13,22 @@ const core_bentley_1 = require("@itwin/core-bentley");
 const core_common_1 = require("@itwin/core-common");
 const TransformerLoggerCategory_1 = require("./TransformerLoggerCategory");
 const core_backend_1 = require("@itwin/core-backend");
-const assert = require("assert");
-const ElementCascadingDeleter_1 = require("./ElementCascadingDeleter");
+const node_assert_1 = require("node:assert");
+const ElementAspectCleanup_1 = require("./ElementAspectCleanup");
 const ecschema_metadata_1 = require("@itwin/ecschema-metadata");
+const IModelTransformerError_1 = require("./IModelTransformerError");
+const ElementBulkDelete_1 = require("./ElementBulkDelete");
 const loggerCategory = TransformerLoggerCategory_1.TransformerLoggerCategory.IModelImporter;
+/** Lists the first kept references for a log message. */
+function formatKeptReferences(keptReferences) {
+    const maxListed = 10;
+    const listed = [...keptReferences]
+        .slice(0, maxListed)
+        .map(([elementId, referencingId]) => `${elementId} (referenced by ${referencingId})`)
+        .join(", ");
+    const unlisted = keptReferences.size - maxListed;
+    return unlisted > 0 ? `${listed}, and ${unlisted} more` : listed;
+}
 /** Base class for importing data into an iModel.
  * @see [iModel Transformation and Data Exchange]($docs/learning/transformer/index.md)
  * @see [IModelExporter]($transformer)
@@ -26,6 +38,23 @@ const loggerCategory = TransformerLoggerCategory_1.TransformerLoggerCategory.IMo
 class IModelImporter {
     /** The read/write target iModel. */
     targetDb;
+    /** The [[EditTxn]] used for write operations on the target iModel.
+     * @beta
+     */
+    _editTxn;
+    /** The [[EditTxn]] used for write operations on the target iModel.
+     * @beta
+     */
+    get editTxn() {
+        return this._editTxn;
+    }
+    _elementAspectCleanup;
+    /** Deletes replaceable ElementAspects through this importer's customized deletion callback.
+     * @internal
+     */
+    get elementAspectCleanup() {
+        return this._elementAspectCleanup;
+    }
     /** resolved initialization options for the importer
      * @beta
      */
@@ -39,6 +68,7 @@ class IModelImporter {
      * To resolve code values to their intended values call [[IModelImporter.resolveDuplicateCodeValues]].
      */
     _duplicateCodeValueMap;
+    _entityExistenceCaches = new Set();
     /**
      * A set of elementIds that the transformer adds to while exporting elements to indicate that the element already exists in the target.
      * Defaults to an empty set.
@@ -52,9 +82,10 @@ class IModelImporter {
      * @note This set should stay small, as right after the transformer pushes to it, the importer will remove from the set.
      */
     _elementsToUpdateDuringPreserveIds = new Set([]);
-    /** The set of elements that should not be updated by this IModelImporter.
-     * Defaults to an empty set.
+    /** The set of target elements that this importer must not directly update or request for deletion.
+     * Defaults to an empty set and is populated by consumers or custom transformers.
      * @note Adding an element to this set is typically necessary when remapping a source element to one that already exists in the target and already has the desired properties.
+     * @note Deletion protection applies only when the exact element ID is passed to [[deleteElement]] or [[deleteElements]]. It does not protect the element from deletion through a parent, containing model, or other cascading dependency. Consumers that need to preserve such an element must also add every requested deletion root whose cascade would delete it.
      */
     doNotUpdateElementIds = new Set([]);
     /** This set is ONLY used for elements that are always present even in an "empty" iModel. We will use this set to filter out changes to root elements if [[IModelTransformOptions.skipPropagateChangesToRootElements]] is false. */
@@ -72,11 +103,12 @@ class IModelImporter {
         "geometryGuid", // cannot compare GeometricModel.GeometryGuid values across iModels
     ]);
     /** Construct a new IModelImporter
-     * @param targetDb The target IModelDb
+     * @param editTxn The [[EditTxn]] to use for write operations on the target iModel. The target db is derived from `editTxn.iModel`.
      * @param options The options that specify how the import should be done.
      */
-    constructor(targetDb, options) {
-        this.targetDb = targetDb;
+    constructor(editTxn, options) {
+        this.targetDb = editTxn.iModel;
+        this._editTxn = editTxn;
         this.options = {
             autoExtendProjectExtents: options?.autoExtendProjectExtents ?? true,
             preserveElementIdsForFiltering: options?.preserveElementIdsForFiltering ?? false,
@@ -84,6 +116,19 @@ class IModelImporter {
             skipPropagateChangesToRootElements: options?.skipPropagateChangesToRootElements ?? true,
         };
         this._duplicateCodeValueMap = new Map();
+        this._elementAspectCleanup = new ElementAspectCleanup_1.ElementAspectCleanup(this.targetDb, this._editTxn, async (aspect) => this.onDeleteElementAspect(aspect));
+    }
+    /** Register a transformation-scoped existence cache for delete invalidation.
+     * @internal
+     */
+    registerEntityExistenceCache(cache) {
+        this._entityExistenceCaches.add(cache);
+    }
+    /** Stop invalidating a transformation-scoped existence cache.
+     * @internal
+     */
+    unregisterEntityExistenceCache(cache) {
+        this._entityExistenceCaches.delete(cache);
     }
     /**
      * Checks [[IModelImportOptions.skipPropagateChangesToRootElements]], [[IModelImporter.rootElementIds]], and [[IModelImporter.doNotUpdateElementIds]] and returns true for 'do not update', false for do 'update'.
@@ -106,9 +151,15 @@ class IModelImporter {
         this._elementsToUpdateDuringPreserveIds.add(elementId);
     }
     /** Import the specified ModelProps (either as an insert or an update) into the target iModel. */
-    importModel(modelProps) {
+    async importModel(modelProps) {
         if (undefined === modelProps.id || !core_bentley_1.Id64.isValidId64(modelProps.id))
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.InvalidId, "Model Id not provided, should be the same as the ModeledElementId");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.InvalidModelId,
+                },
+                message: "Model Id not provided, should be the same as the ModeledElementId",
+            });
         if (this.doNotUpdateElement(modelProps.id)) {
             core_bentley_1.Logger.logInfo(loggerCategory, `Do not update target model ${modelProps.id}`);
             return;
@@ -116,14 +167,14 @@ class IModelImporter {
         try {
             const model = this.targetDb.models.getModel(modelProps.id); // throws IModelError.NotFound if model does not exist
             if (hasEntityChanged(model, modelProps, this._modelPropertiesToIgnore)) {
-                this.onUpdateModel(modelProps);
+                await this.onUpdateModel(modelProps);
             }
         }
         catch (error) {
             // catch NotFound error and insertModel
             if (error instanceof core_common_1.IModelError &&
                 error.errorNumber === core_bentley_1.IModelStatus.NotFound) {
-                this.onInsertModel(modelProps);
+                await this.onInsertModel(modelProps);
                 return;
             }
             throw error;
@@ -132,29 +183,35 @@ class IModelImporter {
     /** Create a new Model from the specified ModelProps and insert it into the target iModel.
      * @note A subclass may override this method to customize insert behavior but should call `super.onInsertModel`.
      */
-    onInsertModel(modelProps) {
+    async onInsertModel(modelProps) {
         try {
-            const modelId = this.targetDb.models.insertModel(modelProps);
+            const modelId = this._editTxn.insertModel(modelProps);
             core_bentley_1.Logger.logInfo(loggerCategory, `Inserted ${this.formatModelForLogger(modelProps)}`);
-            this.trackProgress();
+            await this.trackProgress();
             return modelId;
         }
         catch (error) {
             if (!this.targetDb.containsClass(modelProps.classFullName)) {
-                // replace standard insert error with something more helpful
-                const errorMessage = `Model class "${modelProps.classFullName}" not found in the target iModel. Was the latest version of the schema imported?`;
-                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.InvalidName, errorMessage);
+                // Translate only confirmed missing-class failures; otherwise retain the backend error's identity.
+                core_bentley_1.ITwinError.throwError({
+                    iTwinErrorId: {
+                        scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                        key: IModelTransformerError_1.IModelTransformerError.TargetClassNotFound,
+                    },
+                    message: `Model class "${modelProps.classFullName}" not found in the target iModel. Was the latest version of the schema imported?`,
+                    cause: error,
+                });
             }
-            throw error; // throw original error
+            throw error;
         }
     }
     /** Update an existing Model in the target iModel from the specified ModelProps.
      * @note A subclass may override this method to customize update behavior but should call `super.onUpdateModel`.
      */
-    onUpdateModel(modelProps) {
-        this.targetDb.models.updateModel(modelProps);
+    async onUpdateModel(modelProps) {
+        this._editTxn.updateModel(modelProps);
         core_bentley_1.Logger.logInfo(loggerCategory, `Updated ${this.formatModelForLogger(modelProps)}`);
-        this.trackProgress();
+        await this.trackProgress();
     }
     /** Format a Model for the Logger. */
     formatModelForLogger(modelProps) {
@@ -165,18 +222,18 @@ class IModelImporter {
      * Tries to update an element with the specified element properties.
      * If a duplicate code error occurs, it assigns a new unique code value and retries the update
      */
-    tryUpdateElement(elemProps) {
+    async tryUpdateElement(elemProps) {
         try {
-            this.onUpdateElement(elemProps);
+            await this.onUpdateElement(elemProps);
         }
         catch (err) {
             if (err.errorNumber === core_bentley_1.IModelStatus.DuplicateCode) {
-                assert(elemProps.code.value !== undefined, "NULL code values are always considered unique and cannot clash");
+                (0, node_assert_1.strict)(elemProps.code.value !== undefined, "NULL code values are always considered unique and cannot clash");
                 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                 this._duplicateCodeValueMap.set(elemProps.id, elemProps.code.value);
                 // Using NULL code values as an alternative is not valid because definition elements cannot have NULL code values.
                 elemProps.code.value = core_bentley_1.Guid.createValue();
-                this.onUpdateElement(elemProps);
+                await this.onUpdateElement(elemProps);
             }
             else {
                 throw err;
@@ -184,7 +241,7 @@ class IModelImporter {
         }
     }
     /** Import the specified ElementProps (either as an insert or an update) into the target iModel. */
-    importElement(elementProps) {
+    async importElement(elementProps) {
         if (undefined !== elementProps.id &&
             this.doNotUpdateElement(elementProps.id)) {
             core_bentley_1.Logger.logInfo(loggerCategory, `Do not update target element ${elementProps.id}`);
@@ -192,7 +249,13 @@ class IModelImporter {
         }
         if (this.options.preserveElementIdsForFiltering) {
             if (elementProps.id === undefined) {
-                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadElement, "elementProps.id must be defined during a preserveIds operation");
+                core_bentley_1.ITwinError.throwError({
+                    iTwinErrorId: {
+                        scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                        key: IModelTransformerError_1.IModelTransformerError.ElementIdRequired,
+                    },
+                    message: "elementProps.id must be defined during a preserveIds operation",
+                });
             }
             // Categories are the only element that onInserted will immediately insert a new element (their default subcategory)
             // since default subcategories always exist and always will be inserted after their categories, we treat them as an update
@@ -200,24 +263,24 @@ class IModelImporter {
             // Always present elements (0xe, 0x1, 0x10) also will be updated to prevent duplicate inserts.
             if ((isSubCategory(elementProps) && isDefaultSubCategory(elementProps)) ||
                 this._rootElementIds.has(elementProps.id)) {
-                this.onUpdateElement(elementProps);
+                await this.onUpdateElement(elementProps);
             }
             else {
                 if (this._elementsToUpdateDuringPreserveIds.has(elementProps.id)) {
-                    this.tryUpdateElement(elementProps);
+                    await this.tryUpdateElement(elementProps);
                     this._elementsToUpdateDuringPreserveIds.delete(elementProps.id);
                 }
                 else {
-                    this.onInsertElement(elementProps);
+                    await this.onInsertElement(elementProps);
                 }
             }
         }
         else {
             if (undefined !== elementProps.id) {
-                this.tryUpdateElement(elementProps);
+                await this.tryUpdateElement(elementProps);
             }
             else {
-                elementProps.id = this.onInsertElement(elementProps); // targetElementProps.id assigned by insertElement
+                elementProps.id = await this.onInsertElement(elementProps); // targetElementProps.id assigned by insertElement
             }
         }
         return elementProps.id;
@@ -226,15 +289,15 @@ class IModelImporter {
      * @returns The Id of the newly inserted Element.
      * @note A subclass may override this method to customize insert behavior but should call `super.onInsertElement`.
      */
-    onInsertElement(elementProps) {
+    async onInsertElement(elementProps) {
         try {
-            const elementId = this.targetDb.elements.insertElement(elementProps, {
+            const elementId = this._editTxn.insertElement(elementProps, {
                 forceUseId: this.options.preserveElementIdsForFiltering,
             });
             // set the id like [IModelDb.insertElement]($backend), does, the raw nativeDb method does not
             elementProps.id = elementId;
             core_bentley_1.Logger.logInfo(loggerCategory, `Inserted ${this.formatElementForLogger(elementProps)}`);
-            this.trackProgress();
+            await this.trackProgress();
             if (this.options.simplifyElementGeometry) {
                 this.targetDb.simplifyElementGeometry({
                     id: elementId,
@@ -246,23 +309,34 @@ class IModelImporter {
         }
         catch (error) {
             if (!this.targetDb.containsClass(elementProps.classFullName)) {
-                // replace standard insert error with something more helpful
-                const errorMessage = `Element class "${elementProps.classFullName}" not found in the target iModel. Was the latest version of the schema imported?`;
-                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.InvalidName, errorMessage);
+                core_bentley_1.ITwinError.throwError({
+                    iTwinErrorId: {
+                        scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                        key: IModelTransformerError_1.IModelTransformerError.TargetClassNotFound,
+                    },
+                    message: `Element class "${elementProps.classFullName}" not found in the target iModel. Was the latest version of the schema imported?`,
+                    cause: error,
+                });
             }
-            throw error; // throw original error
+            throw error;
         }
     }
     /** Update an existing Element in the target iModel from the specified ElementProps.
      * @note A subclass may override this method to customize update behavior but should call `super.onUpdateElement`.
      */
-    onUpdateElement(elementProps) {
+    async onUpdateElement(elementProps) {
         if (!elementProps.id) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.InvalidId, "ElementId not provided");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.ElementIdRequired,
+                },
+                message: "ElementId not provided",
+            });
         }
-        this.targetDb.elements.updateElement(elementProps);
+        this._editTxn.updateElement(elementProps);
         core_bentley_1.Logger.logInfo(loggerCategory, `Updated ${this.formatElementForLogger(elementProps)}`);
-        this.trackProgress();
+        await this.trackProgress();
         if (this.options.simplifyElementGeometry) {
             this.targetDb.simplifyElementGeometry({
                 id: elementProps.id,
@@ -271,34 +345,83 @@ class IModelImporter {
             core_bentley_1.Logger.logInfo(loggerCategory, `Simplified element geometry for ${this.formatElementForLogger(elementProps)}`);
         }
     }
-    /** Delete the specified Element (and all its children) from the target iModel.
-     * Will delete special elements like definition elements and subjects.
-     * @note A subclass may override this method to customize delete behavior but should call `super.onDeleteElement`.
+    /** Deletes one target element tree through [[deleteElements]]. */
+    async deleteElement(elementId) {
+        await this.deleteElements(new Set([elementId]));
+    }
+    /** Adds roots required by code-scope dependencies, then deletes the target element trees in as few native operations as their references allow.
+     * Usually one native operation is enough. When a tree contains a definition, such as a category, that another deleted element uses, the elements that use it are deleted first.
+     * Elements that something outside the deleted trees still references are kept, with a warning, and the rest are deleted.
+     * @note An override must call `super.onDeleteElements` once to perform the deletion.
      */
-    onDeleteElement(elementId) {
-        (0, ElementCascadingDeleter_1.deleteElementTreeCascade)(this.targetDb, elementId);
-        core_bentley_1.Logger.logInfo(loggerCategory, `Deleted element ${elementId} and its descendants`);
-        this.trackProgress();
-    }
-    /** Delete the specified Element from the target iModel. */
-    deleteElement(elementId) {
-        if (this.doNotUpdateElement(elementId)) {
-            core_bentley_1.Logger.logInfo(loggerCategory, `Do not delete target element ${elementId}`);
+    async onDeleteElements(elementIds) {
+        const plan = await (0, ElementBulkDelete_1.planBulkDelete)(this.targetDb, elementIds);
+        if (plan.keptReferences.size > 0) {
+            core_bentley_1.Logger.logWarning(loggerCategory, `Kept ${plan.keptReferences.size} elements that elements outside the deleted trees still reference, and the elements that contain them: ${formatKeptReferences(plan.keptReferences)}`);
+        }
+        if (plan.phases.length === 0)
             return;
+        let rootCount = 0;
+        for (const roots of plan.phases) {
+            rootCount += roots.length;
+            this.deleteElementRoots(roots);
+        }
+        core_bentley_1.Logger.logInfo(loggerCategory, `Deleted ${elementIds.size} requested element trees using ${rootCount} native deletion roots in ${plan.phases.length} native operations`);
+        await this.trackProgress(elementIds.size);
+    }
+    deleteElementRoots(roots) {
+        const result = this._editTxn.deleteElements(roots);
+        if (result.status !== core_backend_1.BulkDeleteElementsStatus.Success) {
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.ElementBulkDeleteFailed,
+                },
+                message: `Bulk element deletion failed: status ${core_backend_1.BulkDeleteElementsStatus[result.status]}, ` +
+                    `SQLite status ${result.sqlDeleteStatus}, failed element IDs: ${[
+                        ...result.failedIds,
+                    ].join(", ")}`,
+                status: result.status,
+                sqlDeleteStatus: result.sqlDeleteStatus,
+                failedIds: new Set(result.failedIds),
+            });
         }
-        this.onDeleteElement(elementId);
+    }
+    /** Deletes target element trees, using one native operation unless references between the trees require more.
+     * Requested roots in [[doNotUpdateElementIds]] are skipped. This does not prevent an element in that set from being deleted as part of another root's cascade.
+     * Elements that something outside the deleted trees still references are kept, along with their child elements and sub-models and the elements that contain them. A warning lists them.
+     * @throws [[ElementBulkDeleteError]] if a native operation fails for any root, for example because geometry outside the deleted trees uses a geometry part in them, or because of a reference in a domain schema. The transformer does not check those references first. Deletions from that and earlier native operations stay pending in the caller-owned transaction. Abandon the transaction before retrying.
+     */
+    async deleteElements(elementIds) {
+        const idsToDelete = new Set();
+        for (const elementId of elementIds) {
+            if (!this.doNotUpdateElement(elementId)) {
+                idsToDelete.add(elementId);
+                continue;
+            }
+            core_bentley_1.Logger.logInfo(loggerCategory, `Do not delete target element ${elementId}`);
+        }
+        if (idsToDelete.size === 0)
+            return;
+        await this.onDeleteElements(idsToDelete);
+        // Element deletion cascades can remove descendants and their submodels.
+        for (const cache of this._entityExistenceCaches)
+            cache.clearDb(this.targetDb);
     }
     /** Delete the specified Model from the target iModel.
      * @note A subclass may override this method to customize delete behavior but should call `super.onDeleteModel`.
      */
     async onDeleteModel(modelId) {
-        this.targetDb.models.deleteModel(modelId);
+        this._editTxn.deleteModel(modelId);
         core_bentley_1.Logger.logInfo(loggerCategory, `Deleted model ${modelId}`);
-        this.trackProgress();
+        await this.trackProgress();
     }
     /** Delete the specified Model from the target iModel. */
     async deleteModel(modelId) {
         await this.onDeleteModel(modelId);
+        const modelReference = core_backend_1.EntityReferences.fromEntityType(modelId, core_common_1.ConcreteEntityTypes.Model);
+        for (const cache of this._entityExistenceCaches)
+            cache.invalidate(this.targetDb, modelReference);
     }
     /** Format an Element for the Logger. */
     formatElementForLogger(elementProps) {
@@ -310,14 +433,14 @@ class IModelImporter {
         return `${elementProps.classFullName} ${namePiece}[${elementProps.id}]`;
     }
     /** Import an ElementUniqueAspect into the target iModel. */
-    importElementUniqueAspect(aspectProps) {
+    async importElementUniqueAspect(aspectProps) {
         const aspects = this.targetDb.elements.getAspects(aspectProps.element.id, aspectProps.classFullName);
         if (aspects.length === 0) {
             return this.onInsertElementAspect(aspectProps);
         }
         else if (hasEntityChanged(aspects[0], aspectProps)) {
             aspectProps.id = aspects[0].id;
-            this.onUpdateElementAspect(aspectProps);
+            await this.onUpdateElementAspect(aspectProps);
         }
         return aspects[0].id;
     }
@@ -327,7 +450,7 @@ class IModelImporter {
      * @note For insert vs. update reasons, it is important to process all ElementMultiAspects owned by an Element at once since we don't have aspect-specific provenance.
      * @returns the array of ids of the resulting ElementMultiAspects, in the same order of the aspectPropsArray parameter
      */
-    importElementMultiAspects(aspectPropsArray, 
+    async importElementMultiAspects(aspectPropsArray, 
     /** caller must use this to enforce any aspects added by IModelTransformer are not considered for update */
     filterFunc = () => true) {
         const result = new Array(aspectPropsArray.length).fill(undefined);
@@ -335,91 +458,96 @@ class IModelImporter {
             return result;
         }
         const elementId = aspectPropsArray[0].element.id;
-        // Determine the set of ElementMultiAspect classes to consider
-        const aspectClassFullNames = new Set();
-        aspectPropsArray.forEach((aspectsProps) => {
-            aspectClassFullNames.add(aspectsProps.classFullName);
+        const proposedAspectsByClass = new Map();
+        aspectPropsArray.forEach((props, index) => {
+            const proposedAspects = proposedAspectsByClass.get(props.classFullName) ?? [];
+            proposedAspects.push({ props, index });
+            proposedAspectsByClass.set(props.classFullName, proposedAspects);
         });
         // Handle ElementMultiAspects in groups by class
-        aspectClassFullNames.forEach((aspectClassFullName) => {
-            const proposedAspects = aspectPropsArray
-                .map((props, index) => ({ props, index }))
-                .filter(({ props }) => aspectClassFullName === props.classFullName);
+        for (const [aspectClassFullName, proposedAspects,] of proposedAspectsByClass) {
             const currentAspects = this.targetDb.elements
                 .getAspects(elementId, aspectClassFullName)
                 .map((props, index) => ({ props, index }))
                 .filter(({ props }) => filterFunc(props));
             if (proposedAspects.length >= currentAspects.length) {
-                proposedAspects.forEach(({ props, index: resultIndex }, index) => {
+                for (let index = 0; index < proposedAspects.length; index++) {
+                    const { props, index: resultIndex } = proposedAspects[index];
                     let id;
                     if (index < currentAspects.length) {
                         id = currentAspects[index].props.id;
                         props.id = id;
                         if (hasEntityChanged(currentAspects[index].props, props)) {
-                            this.onUpdateElementAspect(props);
+                            await this.onUpdateElementAspect(props);
                         }
                         id = props.id;
                     }
                     else {
-                        id = this.onInsertElementAspect(props);
+                        id = await this.onInsertElementAspect(props);
                     }
                     result[resultIndex] = id;
-                });
+                }
             }
             else {
-                currentAspects.forEach(({ props, index: resultIndex }, index) => {
-                    let id;
+                for (let index = 0; index < currentAspects.length; index++) {
+                    const { props } = currentAspects[index];
                     if (index < proposedAspects.length) {
-                        id = props.id;
-                        proposedAspects[index].props.id = id;
-                        if (hasEntityChanged(props, proposedAspects[index].props)) {
-                            this.onUpdateElementAspect(proposedAspects[index].props);
+                        const { props: proposedProps, index: resultIndex } = proposedAspects[index];
+                        const id = props.id;
+                        proposedProps.id = id;
+                        if (hasEntityChanged(props, proposedProps)) {
+                            await this.onUpdateElementAspect(proposedProps);
                         }
                         result[resultIndex] = id;
                     }
                     else {
-                        this.onDeleteElementAspect(props);
+                        await this.onDeleteElementAspect(props);
                     }
-                });
+                }
             }
-        });
-        assert(result.every((r) => typeof r !== undefined));
+        }
+        (0, node_assert_1.strict)(result.every((r) => r !== undefined));
         return result;
     }
     /** Insert the ElementAspect into the target iModel.
      * @note A subclass may override this method to customize insert behavior but should call `super.onInsertElementAspect`.
      */
-    onInsertElementAspect(aspectProps) {
+    async onInsertElementAspect(aspectProps) {
         try {
-            const id = this.targetDb.elements.insertAspect(aspectProps);
+            const id = this._editTxn.insertAspect(aspectProps);
             core_bentley_1.Logger.logInfo(loggerCategory, `Inserted ${this.formatElementAspectForLogger(aspectProps)}`);
-            this.trackProgress();
+            await this.trackProgress();
             return id;
         }
         catch (error) {
             if (!this.targetDb.containsClass(aspectProps.classFullName)) {
-                // replace standard insert error with something more helpful
-                const errorMessage = `ElementAspect class "${aspectProps.classFullName}" not found in the target iModel. Was the latest version of the schema imported?`;
-                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.InvalidName, errorMessage);
+                core_bentley_1.ITwinError.throwError({
+                    iTwinErrorId: {
+                        scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                        key: IModelTransformerError_1.IModelTransformerError.TargetClassNotFound,
+                    },
+                    message: `ElementAspect class "${aspectProps.classFullName}" not found in the target iModel. Was the latest version of the schema imported?`,
+                    cause: error,
+                });
             }
-            throw error; // throw original error
+            throw error;
         }
     }
     /** Update the ElementAspect within the target iModel.
      * @note A subclass may override this method to customize update behavior but should call `super.onUpdateElementAspect`.
      */
-    onUpdateElementAspect(aspectProps) {
-        this.targetDb.elements.updateAspect(aspectProps);
+    async onUpdateElementAspect(aspectProps) {
+        this._editTxn.updateAspect(aspectProps);
         core_bentley_1.Logger.logInfo(loggerCategory, `Updated ${this.formatElementAspectForLogger(aspectProps)}`);
-        this.trackProgress();
+        await this.trackProgress();
     }
     /** Delete the specified ElementAspect from the target iModel.
      * @note A subclass may override this method to customize delete behavior but should call `super.onDeleteElementAspect`.
      */
-    onDeleteElementAspect(targetElementAspect) {
-        this.targetDb.elements.deleteAspect(targetElementAspect.id);
+    async onDeleteElementAspect(targetElementAspect) {
+        this._editTxn.deleteAspect(targetElementAspect.id);
         core_bentley_1.Logger.logInfo(loggerCategory, `Deleted ${this.formatElementAspectForLogger(targetElementAspect)}`);
-        this.trackProgress();
+        await this.trackProgress();
     }
     /** Format an ElementAspect for the Logger. */
     formatElementAspectForLogger(elementAspectProps) {
@@ -428,7 +556,7 @@ class IModelImporter {
     /** Import the specified RelationshipProps (either as an insert or an update) into the target iModel.
      * @returns The instance Id of the inserted or updated Relationship.
      */
-    importRelationship(relationshipProps) {
+    async importRelationship(relationshipProps) {
         if (undefined === relationshipProps.sourceId ||
             !core_bentley_1.Id64.isValidId64(relationshipProps.sourceId)) {
             core_bentley_1.Logger.logInfo(loggerCategory, `Ignoring ${relationshipProps.classFullName} instance because of invalid RelationshipProps.sourceId`);
@@ -449,7 +577,7 @@ class IModelImporter {
             // if relationship found, update it
             relationshipProps.id = relationship.id;
             if (hasEntityChanged(relationship, relationshipProps)) {
-                this.onUpdateRelationship(relationshipProps);
+                await this.onUpdateRelationship(relationshipProps);
             }
             return relationshipProps.id;
         }
@@ -461,62 +589,75 @@ class IModelImporter {
      * @returns The instance Id of the newly inserted relationship.
      * @note A subclass may override this method to customize insert behavior but should call `super.onInsertRelationship`.
      */
-    onInsertRelationship(relationshipProps) {
+    async onInsertRelationship(relationshipProps) {
         try {
-            const targetRelInstanceId = this.targetDb.relationships.insertInstance(relationshipProps);
+            const targetRelInstanceId = this._editTxn.insertRelationship(relationshipProps);
             core_bentley_1.Logger.logInfo(loggerCategory, `Inserted ${this.formatRelationshipForLogger(relationshipProps)}`);
-            this.trackProgress();
+            await this.trackProgress();
             return targetRelInstanceId;
         }
         catch (error) {
             if (!this.targetDb.containsClass(relationshipProps.classFullName)) {
-                // replace standard insert error with something more helpful
-                const errorMessage = `Relationship class "${relationshipProps.classFullName}" not found in the target iModel. Was the latest version of the schema imported?`;
-                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.InvalidName, errorMessage);
+                core_bentley_1.ITwinError.throwError({
+                    iTwinErrorId: {
+                        scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                        key: IModelTransformerError_1.IModelTransformerError.TargetClassNotFound,
+                    },
+                    message: `Relationship class "${relationshipProps.classFullName}" not found in the target iModel. Was the latest version of the schema imported?`,
+                    cause: error,
+                });
             }
-            throw error; // throw original error
+            throw error;
         }
     }
     /** Update an existing Relationship in the target iModel from the specified RelationshipProps.
      * @note A subclass may override this method to customize update behavior but should call `super.onUpdateRelationship`.
      */
-    onUpdateRelationship(relationshipProps) {
+    async onUpdateRelationship(relationshipProps) {
         if (!relationshipProps.id) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.InvalidId, "Relationship instance Id not provided");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.RelationshipIdRequired,
+                },
+                message: "Relationship instance Id not provided",
+            });
         }
-        this.targetDb.relationships.updateInstance(relationshipProps);
+        this._editTxn.updateRelationship(relationshipProps);
         core_bentley_1.Logger.logInfo(loggerCategory, `Updated ${this.formatRelationshipForLogger(relationshipProps)}`);
-        this.trackProgress();
+        await this.trackProgress();
     }
     /** Delete the specified Relationship from the target iModel. */
-    onDeleteRelationship(relationshipProps) {
+    async onDeleteRelationship(relationshipProps) {
         // Only passing in what deleteInstance actually uses, full relationshipProps is not necessary.
-        this.targetDb.relationships.deleteInstance({
+        this._editTxn.deleteRelationship({
             id: relationshipProps.id,
             classFullName: relationshipProps.classFullName,
         });
         core_bentley_1.Logger.logInfo(loggerCategory, `Deleted relationship ${relationshipProps.classFullName} id=${relationshipProps.id}`);
-        this.trackProgress();
+        await this.trackProgress();
     }
     /** Delete the specified Relationship from the target iModel. */
-    deleteRelationship(relationshipProps) {
-        this.onDeleteRelationship(relationshipProps);
+    async deleteRelationship(relationshipProps) {
+        await this.onDeleteRelationship(relationshipProps);
     }
     /** Format a Relationship for the Logger. */
     formatRelationshipForLogger(relProps) {
         return `${relProps.classFullName} sourceId=[${relProps.sourceId}] targetId=[${relProps.targetId}]`;
     }
     /** Tracks incremental progress */
-    trackProgress() {
-        this._progressCounter++;
-        if (0 === this._progressCounter % this.progressInterval) {
-            this.onProgress();
-        }
+    async trackProgress(increment = 1) {
+        const previousProgressCounter = this._progressCounter;
+        this._progressCounter += increment;
+        const progressCallbacks = Math.floor(this._progressCounter / this.progressInterval) -
+            Math.floor(previousProgressCounter / this.progressInterval);
+        for (let i = 0; i < progressCallbacks; ++i)
+            await this.onProgress();
     }
     /** This method is called when IModelImporter has made incremental progress based on the [[progressInterval]] setting.
      * @note A subclass may override this method to report custom progress but should call `super.onProgress`.
      */
-    onProgress() { }
+    async onProgress() { }
     /** Optionally compute the projectExtents for the target iModel depending on the options for this IModelImporter.
      * @note This method is automatically called from [IModelTransformer.process]($transformer).
      * @see [IModelDb.computeProjectExtents]($backend), [[autoExtendProjectExtents]]
@@ -533,13 +674,15 @@ class IModelImporter {
             const excludeOutliers = typeof this.options.autoExtendProjectExtents === "object"
                 ? this.options.autoExtendProjectExtents.excludeOutliers
                 : false;
-            // If excludeOutliers is true, use the extents without outliers. If extentsWithOutliers is undefined, fall back to extents.
-            const newProjectExtents = excludeOutliers
-                ? computedProjectExtents.extents
-                : (computedProjectExtents.extentsWithOutliers ??
-                    computedProjectExtents.extents);
+            // If excludeOutliers is true, use the extents without outliers.
+            // Otherwise prefer extentsWithOutliers, but fall back to extents if it's undefined or a null range.
+            const extentsWithOutliers = computedProjectExtents.extentsWithOutliers;
+            const useExtentsWithOutliers = !excludeOutliers && extentsWithOutliers && !extentsWithOutliers.isNull;
+            const newProjectExtents = useExtentsWithOutliers
+                ? extentsWithOutliers
+                : computedProjectExtents.extents;
             if (!newProjectExtents.isAlmostEqual(this.targetDb.projectExtents)) {
-                this.targetDb.updateProjectExtents(newProjectExtents);
+                this._editTxn.updateProjectExtents(newProjectExtents);
                 core_bentley_1.Logger.logInfo(loggerCategory, `Updated projectExtents=${JSON.stringify(this.targetDb.projectExtents)}`);
             }
             if (!excludeOutliers &&
@@ -572,7 +715,7 @@ class IModelImporter {
         for (const [elementId, codeValue] of this._duplicateCodeValueMap) {
             const element = this.targetDb.elements.getElement(elementId);
             element.code.value = codeValue;
-            element.update();
+            this._editTxn.updateElement(element.toJSON());
         }
         this._duplicateCodeValueMap.clear();
     }
@@ -580,7 +723,8 @@ class IModelImporter {
      * Needs to be called to perform necessary cleanup operations.
      * By not calling `finalize` there is a risk that data imported into targetDb will not be as expected.
      *
-     * @note No need to call this If using [[IModelTransformer]] as it automatically invokes this method.
+     * @note [[IModelTransformer.process]] invokes this method automatically. Call it explicitly after
+     * composing the transformer's lower-level subset processing methods.
      */
     finalize() {
         this.resolveDuplicateCodeValues();
@@ -595,7 +739,11 @@ exports.IModelImporter = IModelImporter;
  */
 function hasEntityChanged(entity, entityProps, namesToIgnore) {
     let changed = false;
-    entity.forEach((propertyName, property) => {
+    const entityClass = entity.iModel.schemaContext.getSchemaItemSync(entity.schemaItemKey);
+    (0, node_assert_1.strict)(ecschema_metadata_1.EntityClass.isEntityClass(entityClass) ||
+        ecschema_metadata_1.RelationshipClass.isRelationshipClass(entityClass), `Cannot get metadata for ${entity.classFullName}.`);
+    for (const property of entityClass.getPropertiesSync()) {
+        const propertyName = property.name;
         if (!changed) {
             if (namesToIgnore && namesToIgnore.has(propertyName)) {
                 // skip
@@ -610,7 +758,7 @@ function hasEntityChanged(entity, entityProps, namesToIgnore) {
                 changed = hasValueChanged(entity.asAny[core_common_1.ECJsNames.toJsName(propertyName)], entityProps[core_common_1.ECJsNames.toJsName(propertyName)]);
             }
         }
-    });
+    }
     return changed;
 }
 /** Returns true if the specified binary values are different. */
@@ -640,9 +788,21 @@ function isDefaultSubCategory(props) {
     if (props.id === undefined)
         return false;
     if (!core_bentley_1.Id64.isId64(props.id))
-        throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadElement, "subcategory had invalid id");
+        core_bentley_1.ITwinError.throwError({
+            iTwinErrorId: {
+                scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                key: IModelTransformerError_1.IModelTransformerError.InvalidSubCategory,
+            },
+            message: "subcategory had invalid id",
+        });
     if (props.parent?.id === undefined)
-        throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadElement, `subcategory with id ${props.id} had no parent`);
+        core_bentley_1.ITwinError.throwError({
+            iTwinErrorId: {
+                scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                key: IModelTransformerError_1.IModelTransformerError.InvalidSubCategory,
+            },
+            message: `subcategory with id ${props.id} had no parent`,
+        });
     return props.id === core_backend_1.IModelDb.getDefaultSubCategoryId(props.parent.id);
 }
 //# sourceMappingURL=IModelImporter.js.map