@itwin/imodel-transformer 2.0.0-dev.9 → 2.0.0-experimental.1

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 that an owner batch did not reuse, 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();
+    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),
+            });
+        }
     }
-    /** Delete the specified Element from the target iModel. */
-    deleteElement(elementId) {
-        if (this.doNotUpdateElement(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}`);
-            return;
         }
-        this.onDeleteElement(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) {
@@ -309,25 +432,79 @@ class IModelImporter {
                 : "";
         return `${elementProps.classFullName} ${namePiece}[${elementProps.id}]`;
     }
-    /** Import an ElementUniqueAspect into the target iModel. */
-    importElementUniqueAspect(aspectProps) {
-        const aspects = this.targetDb.elements.getAspects(aspectProps.element.id, aspectProps.classFullName);
-        if (aspects.length === 0) {
+    /** Import an ElementUniqueAspect into the target iModel.
+     * @note Only an existing aspect of exactly `aspectProps.classFullName` on the owner is reused, and it is updated only when its properties differ.
+     * If there is none, the owner's unique aspects of a base or derived class are deleted through [[onDeleteElementAspect]] before the aspect is inserted, because iModel unique-aspect writes treat those classes as one slot.
+     * @returns the ID of the reused or inserted aspect
+     */
+    async importElementUniqueAspect(aspectProps) {
+        const elementId = aspectProps.element.id;
+        const existing = this.getTargetAspects(elementId, aspectProps.classFullName)[0];
+        if (existing === undefined) {
+            // iModel unique-aspect writes treat base and derived classes as one slot:
+            // inserting replaces an aspect of a derived class, and deleting an aspect
+            // of a base class also deletes derived ones. Delete related aspects first
+            // so deletion hooks run and later deletions cannot remove the new aspect.
+            for (const aspectId of await this.queryRelatedUniqueAspectIds(elementId, aspectProps.classFullName)) {
+                this._elementAspectCleanup.retain(aspectId);
+                const aspect = (0, ElementAspectCleanup_1.tryGetAspect)(this.targetDb, aspectId);
+                if (aspect !== undefined)
+                    await this.onDeleteElementAspect(aspect);
+            }
             return this.onInsertElementAspect(aspectProps);
         }
-        else if (hasEntityChanged(aspects[0], aspectProps)) {
-            aspectProps.id = aspects[0].id;
-            this.onUpdateElementAspect(aspectProps);
+        this._elementAspectCleanup.retain(existing.id);
+        if (hasEntityChanged(existing, aspectProps)) {
+            aspectProps.id = existing.id;
+            await this.onUpdateElementAspect(aspectProps);
         }
-        return aspects[0].id;
+        return existing.id;
+    }
+    /** Returns the element's target aspects of exactly `classFullName`, in ECInstanceId order.
+     * Inside a transformer owner batch these come from the batch's loaded aspects; otherwise from the target iModel.
+     */
+    getTargetAspects(elementId, classFullName) {
+        return (this._elementAspectCleanup.getAspects(elementId, classFullName) ??
+            // getAspects is polymorphic; keep only the exact class so aspects of a
+            // derived class are handled with their own class.
+            this.targetDb.elements
+                .getAspects(elementId, classFullName)
+                .filter((aspect) => (0, ElementAspectCleanup_1.isSameClass)(aspect, classFullName)));
+    }
+    /** Returns the element's unique aspects whose class is a base or derived class of `classFullName`, excluding that class itself. */
+    async queryRelatedUniqueAspectIds(elementId, classFullName) {
+        // Most owners have no unique aspect of another class; the loaded batch
+        // aspects answer that without a query.
+        const loaded = this._elementAspectCleanup.getAspects(elementId);
+        if (loaded !== undefined &&
+            !loaded.some((aspect) => aspect instanceof core_backend_1.ElementUniqueAspect &&
+                !(0, ElementAspectCleanup_1.isSameClass)(aspect, classFullName)))
+            return [];
+        const ids = [];
+        for await (const row of this.targetDb.createQueryReader(`SELECT aspect.ECInstanceId id FROM bis.ElementUniqueAspect aspect
+       WHERE aspect.Element.Id = :elementId
+         AND aspect.ECClassId <> ec_classid(:classFullName)
+         AND (
+           aspect.ECClassId IN (
+             SELECT SourceECInstanceId FROM meta.ClassHasAllBaseClasses
+             WHERE TargetECInstanceId = ec_classid(:classFullName))
+           OR aspect.ECClassId IN (
+             SELECT TargetECInstanceId FROM meta.ClassHasAllBaseClasses
+             WHERE SourceECInstanceId = ec_classid(:classFullName)))`, new core_common_1.QueryBinder()
+            .bindId("elementId", elementId)
+            .bindString("classFullName", classFullName.replace(".", ":")), { usePrimaryConn: true })) {
+            ids.push(row.id);
+        }
+        return ids;
     }
     /** Import the collection of ElementMultiAspects into the target iModel.
      * @param aspectPropsArray The ElementMultiAspects to import
      * @param filterFunc Optional filter func that is used to exclude target ElementMultiAspects that were added during iModel transformation from the update detection logic.
      * @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.
+     * @note Aspects are grouped by `classFullName`. Each group is matched in order only against existing target aspects of exactly that class: matches are updated when their properties differ, extra props are inserted, and extra target aspects of that class are deleted. Target aspects of other classes, including derived classes, are not changed.
      * @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 +512,104 @@ 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);
-            const currentAspects = this.targetDb.elements
-                .getAspects(elementId, aspectClassFullName)
+        for (const [aspectClassFullName, proposedAspects,] of proposedAspectsByClass) {
+            const currentAspects = this.getTargetAspects(elementId, aspectClassFullName)
                 .map((props, index) => ({ props, index }))
                 .filter(({ props }) => filterFunc(props));
+            for (const { props } of currentAspects)
+                this._elementAspectCleanup.retain(props.id);
             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) {
+        // Also covers overrides that write another owner's aspects through this hook.
+        this._elementAspectCleanup.beforeWrite(aspectProps.element.id);
         try {
-            const id = this.targetDb.elements.insertAspect(aspectProps);
+            const id = this._editTxn.insertAspect(aspectProps);
+            this._elementAspectCleanup.afterWrite();
             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._elementAspectCleanup.beforeWrite(aspectProps.element.id);
+        this._editTxn.updateAspect(aspectProps);
+        this._elementAspectCleanup.afterWrite();
         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._elementAspectCleanup.beforeWrite(targetElementAspect.element.id);
+        this._editTxn.deleteAspect(targetElementAspect.id);
+        this._elementAspectCleanup.afterWrite();
         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 +618,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 +639,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 +651,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 +736,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 +777,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 +785,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 +801,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 +820,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 +850,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