@itwin/imodel-transformer 1.0.0-dev.9 → 1.0.1-customchanges.0

package/lib/cjs/IModelTransformer.js

@@ -19,8 +19,6 @@ const core_common_1 = require("@itwin/core-common");
 const IModelExporter_1 = require("./IModelExporter");
 const IModelImporter_1 = require("./IModelImporter");
 const TransformerLoggerCategory_1 = require("./TransformerLoggerCategory");
-const PendingReferenceMap_1 = require("./PendingReferenceMap");
-const EntityMap_1 = require("./EntityMap");
 const IModelCloneContext_1 = require("./IModelCloneContext");
 const EntityUnifier_1 = require("./EntityUnifier");
 const Algo_1 = require("./Algo");
@@ -31,30 +29,6 @@ const nullLastProvenanceEntityInfo = {
     aspectVersion: "",
     aspectKind: core_backend_1.ExternalSourceAspect.Kind.Element,
 };
-/**
- * A container for tracking the state of a partially committed entity and finalizing it when it's ready to be fully committed
- * @internal
- */
-class PartiallyCommittedEntity {
-    constructor(
-    /**
-     * A set of "model|element ++ ID64" pairs, (e.g. `model0x11` or `element0x12`)
-     * It is possible for the submodel of an element to be separately resolved from the actual element,
-     * so its resolution must be tracked separately
-     */
-    _missingReferences, _onComplete) {
-        this._missingReferences = _missingReferences;
-        this._onComplete = _onComplete;
-    }
-    resolveReference(id) {
-        this._missingReferences.delete(id);
-        if (this._missingReferences.size === 0)
-            this._onComplete();
-    }
-    forceComplete() {
-        this._onComplete();
-    }
-}
 /**
  * Apply a function to each Id64 in a supported container type of Id64s.
  * Currently only supports raw Id64String or RelatedElement-like objects containing an `id` property that is a Id64String,
@@ -172,7 +146,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         if (this._isProvenanceInitTransform) {
             return "forward";
         }
-        if (!this._isSynchronization) {
+        if (!this._options.argsForProcessChanges) {
             return "not-sync";
         }
         try {
@@ -217,14 +191,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      */
     constructor(source, target, options) {
         super();
-        /** map of (unprocessed element, referencing processed element) pairs to the partially committed element that needs the reference resolved
-         * and have some helper methods below for now */
-        this._pendingReferences = new PendingReferenceMap_1.PendingReferenceMap();
         /** a set of elements for which source provenance will be explicitly tracked by ExternalSourceAspects */
         this._elementsWithExplicitlyTrackedProvenance = new Set();
-        /** map of partially committed entities to their partial commit progress */
-        this._partiallyCommittedEntities = new EntityMap_1.EntityMap();
-        this._isSynchronization = false;
+        this._partiallyCommittedElementIds = new Set();
+        this._partiallyCommittedAspectIds = new Set();
         /**
          * A private variable meant to be set by tests which have an outdated way of setting up transforms. In all synchronizations today we expect to find an ESA in the branch db which describes the master -> branch relationship.
          * The exception to this is the first transform aka the provenance initializing transform which requires that the master imodel and the branch imodel are identical at the time of provenance initialization.
@@ -233,10 +203,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
          */
         this._allowNoScopingESA = false;
         this._changesetRanges = undefined;
-        /** Set of entity keys which were not exported and don't need to be tracked for pending reference resolution.
-         * @note Currently only tracks elements which were not exported.
-         */
-        this._skippedEntities = new Set();
         /**
          * Previously the transformer would insert provenance always pointing to the "target" relationship.
          * It should (and now by default does) instead insert provenance pointing to the provenanceSource
@@ -276,7 +242,12 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             // eslint-disable-next-line deprecation/deprecation
             danglingReferencesBehavior: options?.danglingReferencesBehavior ?? "reject",
             branchRelationshipDataBehavior: options?.branchRelationshipDataBehavior ?? "reject",
+            skipPropagateChangesToRootElements: options?.skipPropagateChangesToRootElements ?? true,
         };
+        // check if authorization client is defined
+        if (core_backend_1.IModelHost.authorizationClient === undefined) {
+            core_bentley_1.Logger.logWarning(loggerCategory, "Authorization client is not set in IModelHost. If the transformer needs an accessToken, then it will fail.");
+        }
         this._isProvenanceInitTransform = this._options
             .wasSourceIModelCopiedToTarget
             ? true
@@ -360,9 +331,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         core_bentley_1.Logger.logInfo(loggerCategory, `this._includeSourceProvenance=${this._options.includeSourceProvenance}`);
         core_bentley_1.Logger.logInfo(loggerCategory, `this._cloneUsingBinaryGeometry=${this._options.cloneUsingBinaryGeometry}`);
         core_bentley_1.Logger.logInfo(loggerCategory, `this._wasSourceIModelCopiedToTarget=${this._options.wasSourceIModelCopiedToTarget}`);
-        core_bentley_1.Logger.logInfo(loggerCategory, 
-        // eslint-disable-next-line deprecation/deprecation
-        `this._isReverseSynchronization=${this._options.isReverseSynchronization}`);
         core_bentley_1.Logger.logInfo(TransformerLoggerCategory_1.TransformerLoggerCategory.IModelImporter, `this.importer.autoExtendProjectExtents=${JSON.stringify(this.importer.options.autoExtendProjectExtents)}`);
         core_bentley_1.Logger.logInfo(TransformerLoggerCategory_1.TransformerLoggerCategory.IModelImporter, `this.importer.simplifyElementGeometry=${this.importer.options.simplifyElementGeometry}`);
     }
@@ -605,8 +573,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         let madeChange = false;
         if (this._options.branchRelationshipDataBehavior !== "unsafe-migrate")
             return madeChange;
-        const fallbackSyncVersionToUse = this._options.unsafeFallbackSyncVersion ?? "";
-        const fallbackReverseSyncVersionToUse = this._options.unsafeFallbackReverseSyncVersion ?? "";
+        const fallbackSyncVersionToUse = this._options.argsForProcessChanges?.unsafeFallbackSyncVersion ?? "";
+        const fallbackReverseSyncVersionToUse = this._options.argsForProcessChanges?.unsafeFallbackReverseSyncVersion ??
+            "";
         if (aspectProps.version === undefined ||
             (aspectProps.version === "" &&
                 aspectProps.version !== fallbackSyncVersionToUse)) {
@@ -744,7 +713,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             targetScopeElementId: this.targetScopeElementId,
             isReverseSynchronization: this.isReverseSynchronization,
             fn,
-            skipPropagateChangesToRootElements: this._options.skipPropagateChangesToRootElements ?? false,
+            skipPropagateChangesToRootElements: this._options.skipPropagateChangesToRootElements ?? true,
         });
     }
     /**
@@ -866,7 +835,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     }
     /** Returns `true` if *brute force* delete detections should be run.
      * @note This is only called if [[IModelTransformOptions.forceExternalSourceAspectProvenance]] option is true
-     * @note Not relevant for processChanges when change history is known.
+     * @note Not relevant for [[process]] when [[IModelTransformOptions.argsForProcessChanges]] are provided and change history is known.
      */
     shouldDetectDeletes() {
         nodeAssert(this._syncType !== undefined);
@@ -876,9 +845,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * Detect Element deletes using ExternalSourceAspects in the target iModel and a *brute force* comparison against Elements
      * in the source iModel.
      * @deprecated in 1.x. Do not use this. // FIXME<MIKE>: how to better explain this?
-     * This method is only called during [[processAll]] when the option
+     * This method is only called during [[process]] when [[IModelTransformOptions.argsForProcessChanges]] is undefined and the option
      * [[IModelTransformOptions.forceExternalSourceAspectProvenance]] is enabled. It is not
-     * necessary when using [[processChanges]] since changeset information is sufficient.
+     * necessary when calling [[process]] with [[IModelTransformOptions.argsForProcessChanges]] defined, since changeset information is sufficient.
      * @note you do not need to call this directly unless processing a subset of an iModel.
      * @throws [[IModelError]] If the required provenance information is not available to detect deletes.
      */
@@ -908,12 +877,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             }
         });
     }
-    /**
-     * @deprecated in 3.x, this no longer has any effect except emitting a warning
-     */
-    skipElement(_sourceElement) {
-        core_bentley_1.Logger.logWarning(loggerCategory, "Tried to defer/skip an element, which is no longer necessary");
-    }
     /** Transform the specified sourceElement into ElementProps for the target iModel.
      * @param sourceElement The Element from the source iModel to transform.
      * @returns ElementProps for the target iModel.
@@ -958,85 +921,74 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         nodeAssert(this._hasElementChangedCache !== undefined, "has element changed cache should be initialized by now");
         return this._hasElementChangedCache.has(sourceElement.id);
     }
-    static transformCallbackFor(transformer, entity) {
-        if (entity instanceof core_backend_1.Element)
-            return transformer.onTransformElement; // eslint-disable-line @typescript-eslint/unbound-method
-        else if (entity instanceof core_backend_1.Element)
-            return transformer.onTransformModel; // eslint-disable-line @typescript-eslint/unbound-method
-        else if (entity instanceof core_backend_1.Relationship)
-            return transformer.onTransformRelationship; // eslint-disable-line @typescript-eslint/unbound-method
-        else if (entity instanceof core_backend_1.ElementAspect)
-            return transformer.onTransformElementAspect; // eslint-disable-line @typescript-eslint/unbound-method
-        else
-            (0, core_bentley_1.assert)(false, `unreachable; entity was '${entity.constructor.name}' not an Element, Relationship, or ElementAspect`);
-    }
-    /** callback to perform when a partial element says it's ready to be completed
-     * transforms the source element with all references now valid, then updates the partial element with the results
-     */
-    makePartialEntityCompleter(sourceEntity) {
-        return () => {
-            const targetId = this.context.findTargetEntityId(core_backend_1.EntityReferences.from(sourceEntity));
-            if (!core_backend_1.EntityReferences.isValid(targetId))
-                throw Error(`${sourceEntity.id} has not been inserted into the target yet, the completer is invalid. This is a bug.`);
-            const onEntityTransform = IModelTransformer.transformCallbackFor(this, sourceEntity);
-            const updateEntity = EntityUnifier_1.EntityUnifier.updaterFor(this.targetDb, sourceEntity);
-            const targetProps = onEntityTransform.call(this, sourceEntity);
-            if (sourceEntity instanceof core_backend_1.Relationship) {
-                targetProps.sourceId =
-                    this.context.findTargetElementId(sourceEntity.sourceId);
-                targetProps.targetId =
-                    this.context.findTargetElementId(sourceEntity.targetId);
+    completePartiallyCommittedElements() {
+        for (const sourceElementId of this._partiallyCommittedElementIds) {
+            const sourceElement = this.sourceDb.elements.getElement({
+                id: sourceElementId,
+                wantGeometry: this.exporter.wantGeometry,
+                wantBRepData: this.exporter.wantGeometry,
+            });
+            const targetId = this.context.findTargetElementId(sourceElementId);
+            if (core_bentley_1.Id64.isInvalid(targetId)) {
+                throw new Error(`source-target element mapping not found for element "${sourceElementId}" when completing partially committed elements. This is a bug.`);
             }
-            updateEntity({ ...targetProps, id: core_backend_1.EntityReferences.toId64(targetId) });
-            this._partiallyCommittedEntities.delete(sourceEntity);
-        };
+            const targetProps = this.onTransformElement(sourceElement);
+            this.targetDb.elements.updateElement({ ...targetProps, id: targetId });
+        }
     }
-    /** collect references this entity has that are yet to be mapped, and if there are any
-     * create a [[PartiallyCommittedEntity]] to track resolution of those references
-     */
-    collectUnmappedReferences(entity) {
-        const missingReferences = new core_common_1.EntityReferenceSet();
-        let thisPartialElem;
-        // eslint-disable-next-line deprecation/deprecation
-        for (const referenceId of entity.getReferenceConcreteIds()) {
-            // TODO: probably need to rename from 'id' to 'ref' so these names aren't so ambiguous
-            const referenceIdInTarget = this.context.findTargetEntityId(referenceId);
-            const alreadyProcessed = core_backend_1.EntityReferences.isValid(referenceIdInTarget) ||
-                this._skippedEntities.has(referenceId);
-            if (alreadyProcessed)
-                continue;
-            core_bentley_1.Logger.logTrace(loggerCategory, `Deferring resolution of reference '${referenceId}' of element '${entity.id}'`);
-            const referencedExistsInSource = EntityUnifier_1.EntityUnifier.exists(this.sourceDb, {
-                entityReference: referenceId,
+    completePartiallyCommittedAspects() {
+        for (const sourceAspectId of this._partiallyCommittedAspectIds) {
+            const sourceAspect = this.sourceDb.elements.getAspect(sourceAspectId);
+            const targetAspectId = this.context.findTargetAspectId(sourceAspectId);
+            if (core_bentley_1.Id64.isInvalid(targetAspectId)) {
+                throw new Error(`source-target aspect mapping not found for aspect "${sourceAspectId}" when completing partially committed aspects. This is a bug.`);
+            }
+            const targetAspectProps = this.onTransformElementAspect(sourceAspect);
+            this.targetDb.elements.updateAspect({
+                ...targetAspectProps,
+                id: targetAspectId,
             });
-            if (!referencedExistsInSource) {
-                core_bentley_1.Logger.logWarning(loggerCategory, `Source ${EntityUnifier_1.EntityUnifier.getReadableType(entity)} (${entity.id}) has a dangling reference to (${referenceId})`);
-                switch (this._options.danglingReferencesBehavior) {
-                    case "ignore":
-                        continue;
-                    case "reject":
-                        throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NotFound, [
-                            `Found a reference to an element "${referenceId}" that doesn't exist while looking for references of "${entity.id}".`,
-                            "This must have been caused by an upstream application that changed the iModel.",
-                            "You can set the IModelTransformOptions.danglingReferencesBehavior option to 'ignore' to ignore this, but this will leave the iModel",
-                            "in a state where downstream consuming applications will need to handle the invalidity themselves. In some cases, writing a custom",
-                            "transformer to remove the reference and fix affected elements may be suitable.",
-                        ].join("\n"));
+        }
+    }
+    doAllReferencesExistInTarget(entity) {
+        let allReferencesExist = true;
+        for (const referenceId of entity.getReferenceIds()) {
+            const referencedEntityId = core_backend_1.EntityReferences.toId64(referenceId);
+            if (referencedEntityId === core_common_1.IModel.repositoryModelId ||
+                referencedEntityId === core_common_1.IModel.dictionaryId ||
+                referencedEntityId === "0xe") {
+                continue;
+            }
+            if (allReferencesExist &&
+                !core_backend_1.EntityReferences.isValid(this.context.findTargetEntityId(referenceId))) {
+                // if we care about references existing then we cannot return early and must check all other references.
+                if (this._options.danglingReferencesBehavior === "ignore") {
+                    return false;
                 }
+                allReferencesExist = false;
             }
-            if (thisPartialElem === undefined) {
-                thisPartialElem = new PartiallyCommittedEntity(missingReferences, this.makePartialEntityCompleter(entity));
-                if (!this._partiallyCommittedEntities.has(entity))
-                    this._partiallyCommittedEntities.set(entity, thisPartialElem);
+            if (this._options.danglingReferencesBehavior === "reject") {
+                this.assertReferenceExistsInSource(referenceId, entity);
             }
-            missingReferences.add(referenceId);
-            const entityReference = core_backend_1.EntityReferences.from(entity);
-            this._pendingReferences.set({ referenced: referenceId, referencer: entityReference }, thisPartialElem);
+        }
+        return allReferencesExist;
+    }
+    assertReferenceExistsInSource(referenceId, entity) {
+        const referencedExistsInSource = EntityUnifier_1.EntityUnifier.exists(this.sourceDb, {
+            entityReference: referenceId,
+        });
+        if (!referencedExistsInSource) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NotFound, [
+                `Found a reference to an element "${referenceId}" that doesn't exist while looking for references of "${entity.id}".`,
+                "This must have been caused by an upstream application that changed the iModel.",
+                "You can set the IModelTransformOptions.danglingReferencesBehavior option to 'ignore' to ignore this,",
+                `and the referenceId found on "${entity.id}" will not be carried over to corresponding target element.`,
+            ].join("\n"));
         }
     }
     /** Cause the specified Element and its child Elements (if applicable) to be exported from the source iModel and imported into the target iModel.
      * @param sourceElementId Identifies the Element from the source iModel to import.
-     * @note This method is called from [[processChanges]] and [[processAll]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
      */
     async processElement(sourceElementId) {
         await this.initialize();
@@ -1047,7 +999,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     }
     /** Import child elements into the target IModelDb
      * @param sourceElementId Import the child elements of this element in the source IModelDb.
-     * @note This method is called from [[processChanges]] and [[processAll]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
      */
     async processChildElements(sourceElementId) {
         await this.initialize();
@@ -1059,24 +1011,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     shouldExportElement(_sourceElement) {
         return true;
     }
-    onSkipElement(sourceElementId) {
-        if (this.context.findTargetElementId(sourceElementId) !== core_bentley_1.Id64.invalid) {
-            // element already has provenance
-            return;
-        }
-        core_bentley_1.Logger.logInfo(loggerCategory, `Element '${sourceElementId}' won't be exported. Marking its references as resolved`);
-        const elementKey = `e${sourceElementId}`;
-        this._skippedEntities.add(elementKey);
-        // Mark any existing pending references to the skipped element as resolved.
-        for (const referencer of this._pendingReferences.getReferencersByEntityKey(elementKey)) {
-            const key = PendingReferenceMap_1.PendingReference.from(referencer, elementKey);
-            const pendingRef = this._pendingReferences.get(key);
-            if (!pendingRef)
-                continue;
-            pendingRef.resolveReference(elementKey);
-            this._pendingReferences.delete(key);
-        }
-    }
     /**
      * If they haven't been already, import all of the required references
      * @internal do not call, override or implement this, it will be removed
@@ -1143,11 +1077,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     onExportElement(sourceElement) {
         let targetElementId;
         let targetElementProps;
-        if (this._options.preserveElementIdsForFiltering) {
-            targetElementId = sourceElement.id;
-            targetElementProps = this.onTransformElement(sourceElement);
-        }
-        else if (this._options.wasSourceIModelCopiedToTarget) {
+        if (this._options.wasSourceIModelCopiedToTarget) {
             targetElementId = sourceElement.id;
             targetElementProps =
                 this.targetDb.elements.getElementProps(targetElementId);
@@ -1186,17 +1116,40 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         }
         if (!this.hasElementChanged(sourceElement))
             return;
-        this.collectUnmappedReferences(sourceElement);
+        if (!this.doAllReferencesExistInTarget(sourceElement)) {
+            this._partiallyCommittedElementIds.add(sourceElement.id);
+        }
         // targetElementId will be valid (indicating update) or undefined (indicating insert)
         targetElementProps.id = core_bentley_1.Id64.isValid(targetElementId)
             ? targetElementId
             : undefined;
+        if (this._options.preserveElementIdsForFiltering) {
+            const isValid = core_bentley_1.Id64.isValid(targetElementId);
+            if (isValid && targetElementId !== sourceElement.id) {
+                // Element found with different id
+                throw new Error(`Element id(${sourceElement.id}) cannot be preserved. Found a different mapping(${targetElementId}) from source element`);
+            }
+            else if (isValid && targetElementId === sourceElement.id) {
+                // targetElementId is valid (indicating update)
+                this.importer.markElementToUpdateDuringPreserveIds(sourceElement.id);
+            }
+            else if (!isValid) {
+                const sourceInTargetElemProps = this.targetDb.elements.tryGetElementProps(sourceElement.id);
+                // if we don't find mapping for source element in target(invalid) but another element with source id exists in target
+                if (sourceInTargetElemProps) {
+                    // Element id is already taken by another element
+                    throw new Error(`Element id(${sourceElement.id}) cannot be preserved. An unrelated element in the target already uses id: ${sourceElement.id}`);
+                }
+                else {
+                    // Element id in target is available to be remapped
+                    targetElementProps.id = sourceElement.id;
+                }
+            }
+        }
         if (!this._options.wasSourceIModelCopiedToTarget) {
             this.importer.importElement(targetElementProps); // don't need to import if iModel was copied
         }
         this.context.remapElement(sourceElement.id, targetElementProps.id); // targetElementProps.id assigned by importElement
-        // now that we've mapped this elem we can fix unmapped references to it
-        this.resolvePendingReferences(sourceElement);
         // the transformer does not currently 'split' or 'join' any elements, therefore, it does not
         // insert external source aspects because federation guids are sufficient for this.
         // Other transformer subclasses must insert the appropriate aspect (as provided by a TBD API)
@@ -1224,16 +1177,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             this.markLastProvenance(provenance, { isRelationship: false });
         }
     }
-    resolvePendingReferences(entity) {
-        for (const referencer of this._pendingReferences.getReferencers(entity)) {
-            const key = PendingReferenceMap_1.PendingReference.from(referencer, entity);
-            const pendingRef = this._pendingReferences.get(key);
-            if (!pendingRef)
-                continue;
-            pendingRef.resolveReference(core_backend_1.EntityReferences.from(entity));
-            this._pendingReferences.delete(key);
-        }
-    }
     /** Override of [IModelExportHandler.onDeleteElement]($transformer) that is called when [IModelExporter]($transformer) detects that an Element has been deleted from the source iModel.
      * This override propagates the delete to the target iModel via [IModelImporter.deleteElement]($transformer).
      */
@@ -1258,7 +1201,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             return;
         const targetModelProps = this.onTransformModel(sourceModel, targetModeledElementId);
         this.importer.importModel(targetModelProps);
-        this.resolvePendingReferences(sourceModel);
     }
     /** Override of [IModelExportHandler.onDeleteModel]($transformer) that is called when [IModelExporter]($transformer) detects that a [Model]($backend) has been deleted from the source iModel. */
     onDeleteModel(sourceModelId) {
@@ -1332,7 +1274,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     }
     /** Cause the model container, contents, and sub-models to be exported from the source iModel and imported into the target iModel.
      * @param sourceModeledElementId Import this [Model]($backend) from the source IModelDb.
-     * @note This method is called from [[processChanges]] and [[processAll]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
      */
     async processModel(sourceModeledElementId) {
         await this.initialize();
@@ -1342,7 +1284,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @param sourceModelId Import the contents of this model from the source IModelDb.
      * @param targetModelId Import into this model in the target IModelDb. The target model must exist prior to this call.
      * @param elementClassFullName Optional classFullName of an element subclass to limit import query against the source model.
-     * @note This method is called from [[processChanges]] and [[processAll]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
      */
     async processModelContents(sourceModelId, targetModelId, elementClassFullName = core_backend_1.Element.classFullName) {
         await this.initialize();
@@ -1399,46 +1341,50 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         targetModelProps.parentModel = this.context.findTargetElementId(targetModelProps.parentModel);
         return targetModelProps;
     }
-    /** Import elements that were deferred in a prior pass.
-     * @deprecated in 3.x. This method is no longer necessary since the transformer no longer needs to defer elements
-     */
-    async processDeferredElements(_numRetries = 3) { }
-    /** called at the end of a transformation,
+    /**
+     * Called at the end of a transformation,
      * updates the target scope element to say that transformation up through the
      * source's changeset has been performed. Also stores all changesets that occurred
      * during the transformation as "pending synchronization changeset indices" @see TargetScopeProvenanceJsonProps
      *
-     * You generally should not call this function yourself and use [[processChanges]] instead.
+     * You generally should not call this function yourself and use [[process]] with [[IModelTransformOptions.argsForProcessChanges]] provided instead.
      * It is public for unsupported use cases of custom synchronization transforms.
-     * @note if you are not running processChanges in this transformation, this will fail
-     * without setting the `force` option to `true`
+     * @note If [[IModelTransformOptions.argsForProcessChanges]] is not defined in this transformation, this function will return early without updating the sync version,
+     * unless the `initializeReverseSyncVersion` option is set to `true`
+     *
+     * The `initializeReverseSyncVersion` is added to set the reverse synchronization version during a forward synchronization.
+     * When set to `true`, it saves the reverse sync version as the current changeset of the targetDb. This is typically used for the first transformation between a master and branch iModel.
+     * Setting `initializeReverseSyncVersion` to `true` has the effect of making it so any changesets in the branch iModel at the time of the first transformation will be ignored during any future reverse synchronizations from the branch to the master iModel.
+     *
+     * Note that typically, the reverseSyncVersion is saved as the last changeset merged from the branch into master.
+     * Setting initializeReverseSyncVersion to true during a forward transformation could overwrite this correct reverseSyncVersion and should only be done during the first transformation between a master and branch iModel.
      */
-    updateSynchronizationVersion({ force = false } = {}) {
-        const notForcedAndHasNoChangesAndIsntProvenanceInit = !force &&
-            this._sourceChangeDataState !== "has-changes" &&
-            !this._isProvenanceInitTransform;
-        if (notForcedAndHasNoChangesAndIsntProvenanceInit)
+    updateSynchronizationVersion({ initializeReverseSyncVersion = false, } = {}) {
+        const shouldSkipSyncVersionUpdate = !initializeReverseSyncVersion &&
+            this._sourceChangeDataState !== "has-changes";
+        if (shouldSkipSyncVersionUpdate)
             return;
         nodeAssert(this._targetScopeProvenanceProps);
         const sourceVersion = `${this.sourceDb.changeset.id};${this.sourceDb.changeset.index}`;
         const targetVersion = `${this.targetDb.changeset.id};${this.targetDb.changeset.index}`;
-        if (this._isProvenanceInitTransform) {
-            this._targetScopeProvenanceProps.version = sourceVersion;
-            this._targetScopeProvenanceProps.jsonProperties.reverseSyncVersion =
-                targetVersion;
-        }
-        else if (this.isReverseSynchronization) {
+        if (this.isReverseSynchronization) {
             const oldVersion = this._targetScopeProvenanceProps.jsonProperties.reverseSyncVersion;
             core_bentley_1.Logger.logInfo(loggerCategory, `updating reverse version from ${oldVersion} to ${sourceVersion}`);
             this._targetScopeProvenanceProps.jsonProperties.reverseSyncVersion =
                 sourceVersion;
         }
-        else if (!this.isReverseSynchronization) {
+        else {
             core_bentley_1.Logger.logInfo(loggerCategory, `updating sync version from ${this._targetScopeProvenanceProps.version} to ${sourceVersion}`);
             this._targetScopeProvenanceProps.version = sourceVersion;
+            // save reverse sync version
+            if (initializeReverseSyncVersion) {
+                core_bentley_1.Logger.logInfo(loggerCategory, `updating reverse sync version from ${this._targetScopeProvenanceProps.jsonProperties.reverseSyncVersion} to ${targetVersion}`);
+                this._targetScopeProvenanceProps.jsonProperties.reverseSyncVersion =
+                    targetVersion;
+            }
         }
-        if (this._isSynchronization ||
-            (this._startingChangesetIndices && this._isProvenanceInitTransform)) {
+        if (this._options.argsForProcessChanges ||
+            (this._startingChangesetIndices && initializeReverseSyncVersion)) {
             nodeAssert(this.targetDb.changeset.index !== undefined &&
                 this._startingChangesetIndices !== undefined, "updateSynchronizationVersion was called without change history");
             const jsonProps = this._targetScopeProvenanceProps.jsonProperties;
@@ -1446,16 +1392,21 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             core_bentley_1.Logger.logTrace(loggerCategory, `previous pendingSyncChanges: ${jsonProps.pendingSyncChangesetIndices}`);
             const pendingSyncChangesetIndicesKey = "pendingSyncChangesetIndices";
             const pendingReverseSyncChangesetIndicesKey = "pendingReverseSyncChangesetIndices";
-            const [syncChangesetsToClearKey, syncChangesetsToUpdateKey] = this
-                .isReverseSynchronization
-                ? [
-                    pendingReverseSyncChangesetIndicesKey,
-                    pendingSyncChangesetIndicesKey,
-                ]
-                : [
-                    pendingSyncChangesetIndicesKey,
-                    pendingReverseSyncChangesetIndicesKey,
-                ];
+            // Determine which keys to clear and update based on the synchronization direction
+            let syncChangesetsToClearKey;
+            let syncChangesetsToUpdateKey;
+            if (this.isReverseSynchronization) {
+                syncChangesetsToClearKey = pendingReverseSyncChangesetIndicesKey;
+                syncChangesetsToUpdateKey = pendingSyncChangesetIndicesKey;
+            }
+            else {
+                syncChangesetsToClearKey = pendingSyncChangesetIndicesKey;
+                syncChangesetsToUpdateKey = pendingReverseSyncChangesetIndicesKey;
+            }
+            // NOTE that as documented in [[processChanges]], this assumes that right after
+            // transformation finalization, the work will be saved immediately, otherwise we've
+            // just marked this changeset as a synchronization to ignore, and the user can add other
+            // stuff to it which would break future synchronizations
             for (let i = this._startingChangesetIndices.target + 1; i <= this.targetDb.changeset.index + 1; i++)
                 jsonProps[syncChangesetsToUpdateKey].push(i);
             // Only keep the changeset indices which are greater than the source, this means they haven't been processed yet.
@@ -1478,23 +1429,11 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this.clearCachedSynchronizationVersion();
     }
     // FIXME<MIKE>: is this necessary when manually using low level transform APIs? (document if so)
-    async finalizeTransformation(options) {
+    finalizeTransformation() {
         this.importer.finalize();
-        this.updateSynchronizationVersion();
-        if (this._partiallyCommittedEntities.size > 0) {
-            const message = [
-                "The following elements were never fully resolved:",
-                [...this._partiallyCommittedEntities.keys()].join(","),
-                "This indicates that either some references were excluded from the transformation",
-                "or the source has dangling references.",
-            ].join("\n");
-            if (this._options.danglingReferencesBehavior === "reject")
-                throw new Error(message);
-            core_bentley_1.Logger.logWarning(loggerCategory, message);
-            for (const partiallyCommittedElem of this._partiallyCommittedEntities.values()) {
-                partiallyCommittedElem.forceComplete();
-            }
-        }
+        this.updateSynchronizationVersion({
+            initializeReverseSyncVersion: this._isProvenanceInitTransform,
+        });
         // TODO: ignore if we remove change cache usage
         if (!this._options.noDetachChangeCache) {
             if (core_backend_1.ChangeSummaryManager.isChangeCacheAttached(this.sourceDb))
@@ -1507,35 +1446,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             this.targetDb.codeValueBehavior = "trim-unicode-whitespace";
         }
         /* eslint-enable @itwin/no-internal */
-        const defaultSaveTargetChanges = () => this.targetDb.saveChanges();
-        await (options?.saveTargetChanges ?? defaultSaveTargetChanges)(this);
-        if (this.isReverseSynchronization)
-            this.sourceDb.saveChanges();
-        const description = `${this._isProvenanceInitTransform
-            ? options?.provenanceInitTransformChangesetDescription ??
-                `initialized branch provenance with master iModel: ${this.sourceDb.iModelId}`
-            : this.isForwardSynchronization
-                ? options?.forwardSyncBranchChangesetDescription ??
-                    `Forward sync of iModel: ${this.sourceDb.iModelId}`
-                : options?.reverseSyncMasterChangesetDescription ??
-                    `Reverse sync of iModel: ${this.sourceDb.iModelId}`}`;
-        if (this.targetDb.isBriefcaseDb()) {
-            // This relies on authorizationClient on iModelHost being defined, otherwise this will fail
-            await this.targetDb.pushChanges({
-                description,
-            });
-        }
-        if (this.isReverseSynchronization && this.sourceDb.isBriefcaseDb()) {
-            // This relies on authorizationClient on iModelHost being defined, otherwise this will fail
-            await this.sourceDb.pushChanges({
-                description: options?.reverseSyncBranchChangesetDescription ??
-                    `Update provenance in response to a reverse sync to iModel: ${this.targetDb.iModelId}`,
-            });
-        }
     }
     /** Imports all relationships that subclass from the specified base class.
      * @param baseRelClassFullName The specified base relationship class.
-     * @note This method is called from [[processChanges]] and [[processAll]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
      */
     async processRelationships(baseRelClassFullName) {
         await this.initialize();
@@ -1608,8 +1522,8 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     }
     /** Detect Relationship deletes using ExternalSourceAspects in the target iModel and a *brute force* comparison against relationships in the source iModel.
      * @deprecated in 1.x. Don't use this anymore
-     * @see processChanges
-     * @note This method is called from [[processAll]] and is not needed by [[processChanges]], so it only needs to be called directly when processing a subset of an iModel.
+     * @see [[process]] with [[IModelTransformOptions.argsForProcessChanges]] provided.
+     * @note This method is called from [[process]] when [[IModelTransformOptions.argsForProcessChanges]] are undefined, so it only needs to be called directly when processing a subset of an iModel.
      * @throws [[IModelError]] If the required provenance information is not available to detect deletes.
      */
     async detectRelationshipDeletes() {
@@ -1676,22 +1590,25 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * This override calls [[onTransformElementAspect]] and then [IModelImporter.importElementUniqueAspect]($transformer) to update the target iModel.
      */
     onExportElementUniqueAspect(sourceAspect) {
-        const targetElementId = this.context.findTargetElementId(sourceAspect.element.id);
-        const targetAspectProps = this.onTransformElementAspect(sourceAspect, targetElementId);
-        this.collectUnmappedReferences(sourceAspect);
+        const targetAspectProps = this.onTransformElementAspect(sourceAspect);
+        if (!this.doAllReferencesExistInTarget(sourceAspect)) {
+            this._partiallyCommittedAspectIds.add(sourceAspect.id);
+        }
         const targetId = this.importer.importElementUniqueAspect(targetAspectProps);
         this.context.remapElementAspect(sourceAspect.id, targetId);
-        this.resolvePendingReferences(sourceAspect);
     }
     /** Override of [IModelExportHandler.onExportElementMultiAspects]($transformer) that imports ElementMultiAspects into the target iModel when they are exported from the source iModel.
      * This override calls [[onTransformElementAspect]] for each ElementMultiAspect and then [IModelImporter.importElementMultiAspects]($transformer) to update the target iModel.
      * @note ElementMultiAspects are handled as a group to make it easier to differentiate between insert, update, and delete.
      */
     onExportElementMultiAspects(sourceAspects) {
-        const targetElementId = this.context.findTargetElementId(sourceAspects[0].element.id);
         // Transform source ElementMultiAspects into target ElementAspectProps
-        const targetAspectPropsArray = sourceAspects.map((srcA) => this.onTransformElementAspect(srcA, targetElementId));
-        sourceAspects.forEach((a) => this.collectUnmappedReferences(a));
+        const targetAspectPropsArray = sourceAspects.map((srcA) => this.onTransformElementAspect(srcA));
+        sourceAspects.forEach((a) => {
+            if (!this.doAllReferencesExistInTarget(a)) {
+                this._partiallyCommittedAspectIds.add(a.id);
+            }
+        });
         // const targetAspectsToImport = targetAspectPropsArray.filter((targetAspect, i) => hasEntityChanged(sourceAspects[i], targetAspect));
         const targetIds = this.importer.importElementMultiAspects(targetAspectPropsArray, (a) => {
             const isExternalSourceAspectFromTransformer = a instanceof core_backend_1.ExternalSourceAspect &&
@@ -1701,16 +1618,14 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         });
         for (let i = 0; i < targetIds.length; ++i) {
             this.context.remapElementAspect(sourceAspects[i].id, targetIds[i]);
-            this.resolvePendingReferences(sourceAspects[i]);
         }
     }
     /** Transform the specified sourceElementAspect into ElementAspectProps for the target iModel.
      * @param sourceElementAspect The ElementAspect from the source iModel to be transformed.
-     * @param _targetElementId The ElementId of the target Element that will own the ElementAspects after transformation.
      * @returns ElementAspectProps for the target iModel.
      * @note A subclass can override this method to provide custom transform behavior.
      */
-    onTransformElementAspect(sourceElementAspect, _targetElementId) {
+    onTransformElementAspect(sourceElementAspect) {
         const targetElementAspectProps = this.context.cloneElementAspect(sourceElementAspect);
         return targetElementAspectProps;
     }
@@ -1750,6 +1665,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             nodeAssert(schemaFileName.length <= systemMaxPathSegmentSize, "Schema name was still long. This is a bug.");
             this._longNamedSchemasMap.set(schema.name, schemaFileName);
         }
+        /* eslint-disable-next-line deprecation/deprecation */
         this.sourceDb.nativeDb.exportSchema(schema.name, this._schemaExportDir, schemaFileName);
         return { schemaPath: path.join(this._schemaExportDir, schemaFileName) };
     }
@@ -1790,7 +1706,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         }
     }
     /** Cause all fonts to be exported from the source iModel and imported into the target iModel.
-     * @note This method is called from [[processChanges]] and [[processAll]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
      */
     async processFonts() {
         // we do not need to initialize for this since no entities are exported
@@ -1802,14 +1718,14 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this.context.importFont(font.id);
     }
     /** Cause all CodeSpecs to be exported from the source iModel and imported into the target iModel.
-     * @note This method is called from [[processChanges]] and [[processAll]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
      */
     async processCodeSpecs() {
         await this.initialize();
         return this.exporter.exportCodeSpecs();
     }
     /** Cause a single CodeSpec to be exported from the source iModel and imported into the target iModel.
-     * @note This method is called from [[processChanges]] and [[processAll]], so it only needs to be called directly when processing a subset of an iModel.
+     * @note This method is called from [[process]], so it only needs to be called directly when processing a subset of an iModel.
      */
     async processCodeSpec(codeSpecName) {
         await this.initialize();
@@ -1833,25 +1749,56 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this.context.remapElement(sourceSubjectId, targetSubjectId);
         await this.processChildElements(sourceSubjectId);
         await this.processSubjectSubModels(sourceSubjectId);
-        return this.processDeferredElements(); // eslint-disable-line deprecation/deprecation
+        this.completePartiallyCommittedElements();
+        this.completePartiallyCommittedAspects();
     }
     /**
      * Initialize prerequisites of processing, you must initialize with an [[InitOptions]] if you
-     * are intending to process changes, but prefer using [[processChanges]] explicitly since it calls this.
+     * are intending to process changes. Callers may wish to explicitly call initialize if they need to execute code after initialize but before [[process]] is called.
      * @note Called by all `process*` functions implicitly.
      * Overriders must call `super.initialize()` first
      */
-    async initialize(args) {
+    async initialize() {
         if (this._initialized)
             return;
-        await this._tryInitChangesetData(args);
+        this.initScopeProvenance();
+        await this._tryInitChangesetData(this._options.argsForProcessChanges);
         await this.context.initialize();
         // need exporter initialized to do remapdeletedsourceentities.
-        await this.exporter.initialize(this.getExportInitOpts(args ?? {}));
+        await this.exporter.initialize(this.getExportInitOpts(this._options.argsForProcessChanges ?? {}));
         // Exporter must be initialized prior to processing changesets in order to properly handle entity recreations (an entity delete followed by an insert of that same entity).
         await this.processChangesets();
         this._initialized = true;
     }
+    async handleCustomChanges(hasElementChangedCache, deleteIdsProcessed) {
+        // The hasElementChangedCache gets populated by changes from this._csFileProps.
+        // Because there is a possibility that someone could manually add ids to exporter.sourceDbChanges, we must separately process exporter.sourceDbChanges and add them to our hasElementChangedCache.
+        // Without this change we risk onExportElement returning early because we use hasElementChangedCache to decide if an element has changed or not.
+        this.exporter.sourceDbChanges?.element.updateIds.forEach((id) => hasElementChangedCache.add(id));
+        this.exporter.sourceDbChanges?.element.insertIds.forEach((id) => hasElementChangedCache.add(id));
+        // This loop is to process all custom deleteIds. Unclear if the special logic is still necessary for relationships or not (TODO!!). For all other entities, we assume that the element is still present in the sourceDb because it is not
+        // a real delete and instead a simulated delete to update filtering criteria between source and target. Since the element is still present, we do not need to call processDeletedOp to find the corresponding targetId.
+        // We can instead rely on `forEachTrackedElement` at the top of processChangesets to find the corresponding targetId.
+        // Note this also assumes we don't need to handle entity recreation for these custom deletes. I.e. a caller of API would not be able to add a custom delete for an entity that was recreated.
+        // a delete followed by an insert.
+        // ASSUME: If a changeset has a deleteId then custom change will never reference it. Is this still true if it was re-inserted? (TODO!!)
+        if (this.exporter.sourceDbChanges?.hasCustomChanges) {
+            for (const id of this.exporter.sourceDbChanges?.relationship.deleteIds.keys() ??
+                []) {
+                if (deleteIdsProcessed?.has(id))
+                    continue;
+                const customData = this.exporter.sourceDbChanges?.getCustomRelationshipDataFromId(id, "relationship");
+                if (customData === undefined) {
+                    core_bentley_1.Logger.logError(loggerCategory, "Custom data not found for relationship.", { id });
+                    continue;
+                }
+                const classFullName = customData.classFullName;
+                const sourceIdOfRelationshipInSource = customData?.sourceIdOfRelationship;
+                const targetIdOfRelationshipInSource = customData?.targetIdOfRelationship;
+                await this.processRelationshipDeleteOp(id, classFullName, sourceIdOfRelationshipInSource, targetIdOfRelationshipInSource);
+            }
+        }
+    }
     /**
      * Reads all the changeset files in the private member of the transformer: _csFileProps and does two things with these changesets.
      * Finds the corresponding target entity for any deleted source entities and remaps the sourceId to the targetId.
@@ -1863,8 +1810,14 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this.forEachTrackedElement((sourceElementId, targetElementId) => {
             this.context.remapElement(sourceElementId, targetElementId);
         });
-        if (this._csFileProps === undefined || this._csFileProps.length === 0)
-            return;
+        this.exporter.addCustomChanges();
+        if (this._csFileProps === undefined || this._csFileProps.length === 0) {
+            if (this.exporter.sourceDbChanges?.isEmpty)
+                return;
+            // our sourcedbChanges aren't empty (probably due to someone adding custom changes), change our sourceChangeDataState to has-changes
+            if (this._sourceChangeDataState === "no-changes")
+                this._sourceChangeDataState = "has-changes";
+        }
         const hasElementChangedCache = new Set();
         const relationshipECClassIdsToSkip = new Set();
         for await (const row of this.sourceDb.createQueryReader("SELECT ECInstanceId FROM ECDbMeta.ECClassDef where ECInstanceId IS (BisCore.ElementDrivesElement)")) {
@@ -1892,7 +1845,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 alreadyImportedModelInserts.add(targetModelId);
         });
         this._deletedSourceRelationshipData = new Map();
-        for (const csFile of this._csFileProps) {
+        /** a map of element ids to this transformation scope's ESA data for that element, in case the ESA is deleted in the target */
+        const elemIdToScopeEsa = new Map();
+        const deleteIdsProcessed = new Set();
+        for (const csFile of this._csFileProps ?? []) {
             const csReader = core_backend_1.SqliteChangesetReader.openFile({
                 fileName: csFile.pathname,
                 db: this.sourceDb,
@@ -1904,8 +1860,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 ecChangeUnifier.appendFrom(csAdaptor);
             }
             const changes = [...ecChangeUnifier.instances];
-            /** a map of element ids to this transformation scope's ESA data for that element, in case the ESA is deleted in the target */
-            const elemIdToScopeEsa = new Map();
             for (const change of changes) {
                 if (change.ECClassId !== undefined &&
                     relationshipECClassIdsToSkip.has(change.ECClassId))
@@ -1913,7 +1867,8 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 const changeType = change.$meta?.op;
                 if (changeType === "Deleted" &&
                     change?.$meta?.classFullName === core_backend_1.ExternalSourceAspect.classFullName &&
-                    change.Scope.Id === this.targetScopeElementId) {
+                    change.Scope.Id === this.targetScopeElementId &&
+                    change.Kind === core_backend_1.ExternalSourceAspect.Kind.Element) {
                     elemIdToScopeEsa.set(change.Element.Id, change);
                 }
                 else if ((changeType === "Inserted" || changeType === "Updated") &&
@@ -1932,115 +1887,151 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 if (changeType !== "Deleted" ||
                     relationshipECClassIdsToSkip.has(ecClassId))
                     continue;
-                await this.processDeletedOp(change, elemIdToScopeEsa, relationshipECClassIds.has(ecClassId ?? ""), alreadyImportedElementInserts, alreadyImportedModelInserts);
+                if (relationshipECClassIds.has(ecClassId)) {
+                    if (change.$meta?.classFullName === undefined) {
+                        core_bentley_1.Logger.logError(loggerCategory, "ClassFullName was not found for relationship when reading changes. Relationship delete will not propagate.", { relationshipId: change.ECInstanceId, ecClassId });
+                        continue;
+                    }
+                    if (change.SourceECInstanceId === undefined ||
+                        change.TargetECInstanceId === undefined) {
+                        core_bentley_1.Logger.logError(loggerCategory, "SourceECInstanceId or TargetECInstanceId was not found for relationship when reading changes. Relationship delete will not propagate.", {
+                            relationshipId: change.ECInstanceId,
+                            ecClassId,
+                            classFullName: change.$meta.classFullName,
+                        });
+                        continue;
+                    }
+                    await this.processRelationshipDeleteOp(change.ECInstanceId, change.$meta.classFullName, change.SourceECInstanceId, change.TargetECInstanceId);
+                }
+                else {
+                    await this.processElementDeleteOp(change.ECInstanceId, alreadyImportedElementInserts, alreadyImportedModelInserts, elemIdToScopeEsa, change.FederationGuid);
+                }
+                deleteIdsProcessed.add(change.ECInstanceId);
             }
             csReader.close();
         }
+        await this.handleCustomChanges(hasElementChangedCache, deleteIdsProcessed);
         this._hasElementChangedCache = hasElementChangedCache;
         return;
     }
+    /**
+     * Helper function for processChangesets.
+     * Populates the '_deletedSourceRelationshipData' map, whose key is the id of the relationship in the source and the value is an object used to find that relationship in the target.
+     * @param changedInstanceId The id of the relationship that was deleted
+     * @param classFullName classFullName of relationship
+     * @param sourceIdOfRelationshipInSource the element Id acting as the source of the relationship in the sourceDb
+     * @param targetIdOfRelationshipInSource the element Id acting as the target of the relationship in the sourceDb
+     * @returns
+     */
+    async processRelationshipDeleteOp(changedInstanceId, classFullName, sourceIdOfRelationshipInSource, targetIdOfRelationshipInSource) {
+        // we need a connected iModel with changes to remap elements with deletions
+        const notConnectedModel = this.sourceDb.iTwinId === undefined;
+        const noChanges = this.synchronizationVersion.index === this.sourceDb.changeset.index &&
+            this.exporter.sourceDbChanges?.isEmpty;
+        if (notConnectedModel || noChanges)
+            return;
+        const sourceIdOfRelationshipInTarget = await this.getTargetIdFromSourceId(sourceIdOfRelationshipInSource, true);
+        const targetIdOfRelationshipInTarget = await this.getTargetIdFromSourceId(targetIdOfRelationshipInSource, true);
+        if (sourceIdOfRelationshipInTarget && targetIdOfRelationshipInTarget) {
+            this._deletedSourceRelationshipData.set(changedInstanceId, {
+                classFullName,
+                sourceIdInTarget: sourceIdOfRelationshipInTarget,
+                targetIdInTarget: targetIdOfRelationshipInTarget,
+            });
+        }
+        else if (this.sourceDb === this.provenanceSourceDb) {
+            const relProvenance = this._queryProvenanceForRelationship(changedInstanceId, {
+                classFullName,
+                sourceId: sourceIdOfRelationshipInSource,
+                targetId: targetIdOfRelationshipInSource,
+            });
+            if (relProvenance && relProvenance.relationshipId)
+                this._deletedSourceRelationshipData.set(changedInstanceId, {
+                    classFullName,
+                    relId: relProvenance.relationshipId,
+                    provenanceAspectId: relProvenance.aspectId,
+                });
+        }
+    }
     /**
      * Helper function for processChangesets. Remaps the id of element deleted found in the 'change' to an element in the targetDb.
      * @param change the change to process, must be of changeType "Deleted"
      * @param mapOfDeletedElemIdToScopeEsas a map of elementIds to changedECInstances (which are ESAs). the elementId is not the id of the esa itself, but the elementid that the esa was stored on before the esa's deletion.
      * All ESAs in this map are part of the transformer's scope / ESA data and are tracked in case the ESA is deleted in the target.
-     * @param isRelationship is relationship or not
      * @param alreadyImportedElementInserts used to handle entity recreation and not delete already handled element inserts.
      * @param alreadyImportedModelInserts used to handle entity recreation and not delete already handled model inserts.
      * @returns void
      */
-    async processDeletedOp(change, mapOfDeletedElemIdToScopeEsas, isRelationship, alreadyImportedElementInserts, alreadyImportedModelInserts) {
+    async processElementDeleteOp(changedInstanceId, alreadyImportedElementInserts, alreadyImportedModelInserts, mapOfDeletedElemIdToScopeEsas, federationGuid) {
         // we need a connected iModel with changes to remap elements with deletions
         const notConnectedModel = this.sourceDb.iTwinId === undefined;
-        const noChanges = this.synchronizationVersion.index === this.sourceDb.changeset.index;
+        const noChanges = this.synchronizationVersion.index === this.sourceDb.changeset.index &&
+            this.exporter.sourceDbChanges?.isEmpty;
         if (notConnectedModel || noChanges)
             return;
+        let targetId = await this.getTargetIdFromSourceId(changedInstanceId, false, mapOfDeletedElemIdToScopeEsas, federationGuid);
+        if (targetId === undefined && this.sourceDb === this.provenanceSourceDb) {
+            targetId = this._queryProvenanceForElement(changedInstanceId);
+        }
+        // since we are processing one changeset at a time, we can see local source deletes
+        // of entities that were never synced and can be safely ignored
+        const deletionNotInTarget = !targetId;
+        if (deletionNotInTarget)
+            return;
+        this.context.remapElement(changedInstanceId, targetId);
+        // If an entity insert and an entity delete both point to the same entity in target iModel, that means that entity was recreated.
+        // In such case an entity update will be triggered and we no longer need to delete the entity.
+        if (alreadyImportedElementInserts.has(targetId)) {
+            this.exporter.sourceDbChanges?.element.deleteIds.delete(changedInstanceId);
+        }
+        if (alreadyImportedModelInserts.has(targetId)) {
+            this.exporter.sourceDbChanges?.model.deleteIds.delete(changedInstanceId);
+        }
+    }
+    /**
+     * Find the corresponding id in the targetDb given a id from the sourceDb
+     * @param id the id in the source that we want to find the target id for
+     * @param isRelationship Changes the way we look for the federationGuid , if true we look for the federationGuid on the element itself, if false we expect it to be passed in because it was part of the ChangedECInstance.
+     * Typically the source and targetIds of the relationship and not the relationshipId itself is passed to this function
+     * @param mapOfDeletedElemIdToScopeEsas a map of elementIds to changedECInstances (which are ESAs). the elementId is not the id of the esa itself, but the elementid that the esa was stored on before the esa's deletion.
+     * All ESAs in this map are part of the transformer's scope / ESA data and are tracked in case the ESA is deleted in the target.
+     * @param federationGuid
+     * @returns id of the corresponding entity in the targetDb or undefined if not found
+     */
+    async getTargetIdFromSourceId(id, isRelationship, mapOfDeletedElemIdToScopeEsas, federationGuid) {
         /**
          * if our ChangedECInstance is in the provenanceDb, then we can use the ids we find in the ChangedECInstance to query for ESAs.
          * This is because the ESAs are stored on an element Id thats present in the provenanceDb.
          */
         const changeDataInProvenanceDb = this.sourceDb === this.provenanceDb;
-        const getTargetIdFromSourceId = async (id) => {
-            let identifierValue;
-            let element;
-            if (isRelationship) {
-                element = this.sourceDb.elements.tryGetElement(id);
-            }
-            const fedGuid = isRelationship
-                ? element?.federationGuid
-                : change.FederationGuid;
-            if (changeDataInProvenanceDb) {
-                // TODO: clarify what happens if there are multiple (e.g. elements were merged)
-                for await (const row of this.sourceDb.createQueryReader("SELECT esa.Identifier FROM bis.ExternalSourceAspect esa WHERE Scope.Id=:scopeId AND Kind=:kind AND Element.Id=:relatedElementId LIMIT 1", core_common_1.QueryBinder.from([
-                    this.targetScopeElementId,
-                    core_backend_1.ExternalSourceAspect.Kind.Element,
-                    id,
-                ]))) {
-                    identifierValue = row.Identifier;
-                }
-                identifierValue =
-                    identifierValue ?? mapOfDeletedElemIdToScopeEsas.get(id)?.Identifier;
-            }
-            // Check for targetId by an esa first
-            if (changeDataInProvenanceDb && identifierValue) {
-                const targetId = identifierValue;
-                return targetId;
-            }
-            // Check for targetId using sourceId's fedguid if we didn't find an esa.
-            if (fedGuid) {
-                const targetId = this._queryElemIdByFedGuid(this.targetDb, fedGuid);
-                return targetId;
-            }
-            return undefined;
-        };
-        const changedInstanceId = change.ECInstanceId;
+        let identifierValue;
+        let element;
         if (isRelationship) {
-            const sourceIdOfRelationshipInSource = change.SourceECInstanceId;
-            const targetIdOfRelationshipInSource = change.TargetECInstanceId;
-            const classFullName = change.$meta?.classFullName;
-            const sourceIdOfRelationshipInTarget = await getTargetIdFromSourceId(sourceIdOfRelationshipInSource);
-            const targetIdOfRelationshipInTarget = await getTargetIdFromSourceId(targetIdOfRelationshipInSource);
-            if (sourceIdOfRelationshipInTarget && targetIdOfRelationshipInTarget) {
-                this._deletedSourceRelationshipData.set(changedInstanceId, {
-                    classFullName: classFullName ?? "",
-                    sourceIdInTarget: sourceIdOfRelationshipInTarget,
-                    targetIdInTarget: targetIdOfRelationshipInTarget,
-                });
-            }
-            else if (this.sourceDb === this.provenanceSourceDb) {
-                const relProvenance = this._queryProvenanceForRelationship(changedInstanceId, {
-                    classFullName: classFullName ?? "",
-                    sourceId: sourceIdOfRelationshipInSource,
-                    targetId: targetIdOfRelationshipInSource,
-                });
-                if (relProvenance && relProvenance.relationshipId)
-                    this._deletedSourceRelationshipData.set(changedInstanceId, {
-                        classFullName: classFullName ?? "",
-                        relId: relProvenance.relationshipId,
-                        provenanceAspectId: relProvenance.aspectId,
-                    });
-            }
+            element = this.sourceDb.elements.tryGetElement(id);
         }
-        else {
-            let targetId = await getTargetIdFromSourceId(changedInstanceId);
-            if (targetId === undefined && this.sourceDb === this.provenanceSourceDb) {
-                targetId = this._queryProvenanceForElement(changedInstanceId);
-            }
-            // since we are processing one changeset at a time, we can see local source deletes
-            // of entities that were never synced and can be safely ignored
-            const deletionNotInTarget = !targetId;
-            if (deletionNotInTarget)
-                return;
-            this.context.remapElement(changedInstanceId, targetId);
-            // If an entity insert and an entity delete both point to the same entity in target iModel, that means that entity was recreated.
-            // In such case an entity update will be triggered and we no longer need to delete the entity.
-            if (alreadyImportedElementInserts.has(targetId)) {
-                this.exporter.sourceDbChanges?.element.deleteIds.delete(changedInstanceId);
-            }
-            if (alreadyImportedModelInserts.has(targetId)) {
-                this.exporter.sourceDbChanges?.model.deleteIds.delete(changedInstanceId);
+        const fedGuid = isRelationship ? element?.federationGuid : federationGuid;
+        // Check for targetId using sourceId's fedguid
+        if (fedGuid) {
+            const targetId = this._queryElemIdByFedGuid(this.targetDb, fedGuid);
+            if (targetId !== undefined)
+                return targetId;
+        }
+        // Check for targetId by esa
+        if (changeDataInProvenanceDb) {
+            // TODO: clarify what happens if there are multiple (e.g. elements were merged)
+            for await (const row of this.sourceDb.createQueryReader("SELECT esa.Identifier FROM bis.ExternalSourceAspect esa WHERE Scope.Id=:scopeId AND Kind=:kind AND Element.Id=:relatedElementId LIMIT 1", core_common_1.QueryBinder.from([
+                this.targetScopeElementId,
+                core_backend_1.ExternalSourceAspect.Kind.Element,
+                id,
+            ]))) {
+                identifierValue = row.Identifier;
             }
+            identifierValue =
+                identifierValue ?? mapOfDeletedElemIdToScopeEsas?.get(id)?.Identifier;
+            if (identifierValue)
+                return identifierValue;
         }
+        return undefined;
     }
     async _tryInitChangesetData(args) {
         if (!args ||
@@ -2055,10 +2046,11 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             this._csFileProps = [];
             return;
         }
+        const startChangeset = "startChangeset" in args ? args.startChangeset : undefined;
         // NOTE: that we do NOT download the changesummary for the last transformed version, we want
         // to ignore those already processed changes
-        const startChangesetIndexOrId = args.startChangeset?.index ??
-            args.startChangeset?.id ??
+        const startChangesetIndexOrId = startChangeset?.index ??
+            startChangeset?.id ??
             this.synchronizationVersion.index + 1;
         const endChangesetId = this.sourceDb.changeset.id;
         const [startChangesetIndex, endChangesetIndex] = await Promise.all([startChangesetIndexOrId, endChangesetId].map(async (indexOrId) => typeof indexOrId === "number"
@@ -2068,11 +2060,11 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 iModelId: this.sourceDb.iModelId,
                 // eslint-disable-next-line deprecation/deprecation
                 changeset: { id: indexOrId },
-                accessToken: args.accessToken,
             })
                 .then((changeset) => changeset.index)));
         const missingChangesets = startChangesetIndex > this.synchronizationVersion.index + 1;
-        if (!this._options.ignoreMissingChangesetsInSynchronizations &&
+        if (!this._options.argsForProcessChanges
+            ?.ignoreMissingChangesetsInSynchronizations &&
             startChangesetIndex !== this.synchronizationVersion.index + 1 &&
             this.synchronizationVersion.index !== -1) {
             throw Error(`synchronization is ${missingChangesets ? "missing changesets" : ""},` +
@@ -2107,13 +2099,40 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this._sourceChangeDataState =
             this._csFileProps.length === 0 ? "no-changes" : "has-changes";
     }
+    /**
+     * The behavior of process is influenced by [[IModelTransformOptions.argsForProcessChanges]] being defined or not defined during construction passed of the IModelTransformer.
+     * @section When argsForProcessChanges are defined:
+     *
+     * Export changes from the source iModel and import the transformed entities into the target iModel.
+     * Inserts, updates, and deletes are determined by inspecting the changeset(s).
+     *
+     * Notes:
+     * - the transformer assumes that you saveChanges after processing changes. You should not modify the iModel after processChanges until saveChanges,
+     * failure to do so may result in corrupted
+     * data loss in future branch operations
+     * - if no startChangesetId or startChangeset option is provided as part of the ProcessChangesOptions, the next unsynchronized changeset
+     * will automatically be determined and used
+     * - To form a range of versions to process, set `startChangesetId` for the start (inclusive) of the desired range and open the source iModel as of the end (inclusive) of the desired range.
+     *
+     * @section When argsForProcessChanges are undefined:
+     *
+     * Export everything from the source iModel and import the transformed entities into the target iModel.
+     *
+     * Notes:
+     * - [[processSchemas]] is not called automatically since the target iModel may want a different collection of schemas.
+     *
+     */
+    async process() {
+        await this.initialize();
+        this.logSettings();
+        return this._options.argsForProcessChanges !== undefined
+            ? this.processChanges(this._options.argsForProcessChanges)
+            : this.processAll();
+    }
     /** Export everything from the source iModel and import the transformed entities into the target iModel.
      * @note [[processSchemas]] is not called automatically since the target iModel may want a different collection of schemas.
      */
-    async processAll(options) {
-        this.logSettings();
-        this.initScopeProvenance();
-        await this.initialize();
+    async processAll() {
         await this.exporter.exportCodeSpecs();
         await this.exporter.exportFonts();
         if (this._options.skipPropagateChangesToRootElements) {
@@ -2125,9 +2144,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         else {
             await this.exporter.exportModel(core_common_1.IModel.repositoryModelId);
         }
+        this.completePartiallyCommittedElements();
         await this.exporter["exportAllAspects"](); // eslint-disable-line @typescript-eslint/dot-notation
+        this.completePartiallyCommittedAspects();
         await this.exporter.exportRelationships(core_backend_1.ElementRefersToElements.classFullName);
-        await this.processDeferredElements(); // eslint-disable-line deprecation/deprecation
         if (this._options.forceExternalSourceAspectProvenance &&
             this.shouldDetectDeletes()) {
             // eslint-disable-next-line deprecation/deprecation
@@ -2138,7 +2158,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         if (this._options.optimizeGeometry)
             this.importer.optimizeGeometry(this._options.optimizeGeometry);
         this.importer.computeProjectExtents();
-        await this.finalizeTransformation(options);
+        this.finalizeTransformation();
     }
     markLastProvenance(sourceAspect, { isRelationship = false }) {
         this._lastProvenanceEntityInfo =
@@ -2155,39 +2175,42 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     }
     /** Export changes from the source iModel and import the transformed entities into the target iModel.
      * Inserts, updates, and deletes are determined by inspecting the changeset(s).
-     * @note the transformer saves and pushes changes when its work is complete.
+     * @note the transformer assumes that you saveChanges after processing changes. You should not
+     * modify the iModel after processChanges until saveChanges, failure to do so may result in corrupted
+     * data loss in future branch operations
      * @note if no startChangesetId or startChangeset option is provided as part of the ProcessChangesOptions, the next unsynchronized changeset
      * will automatically be determined and used
      * @note To form a range of versions to process, set `startChangesetId` for the start (inclusive) of the desired range and open the source iModel as of the end (inclusive) of the desired range.
      */
     async processChanges(options) {
-        this._isSynchronization = true;
-        this.initScopeProvenance();
-        this.logSettings();
-        await this.initialize(options);
         // must wait for initialization of synchronization provenance data
         await this.exporter.exportChanges(this.getExportInitOpts(options));
-        await this.processDeferredElements(); // eslint-disable-line deprecation/deprecation
+        this.completePartiallyCommittedElements();
+        this.completePartiallyCommittedAspects();
         if (this._options.optimizeGeometry)
             this.importer.optimizeGeometry(this._options.optimizeGeometry);
         this.importer.computeProjectExtents();
-        await this.finalizeTransformation(options);
+        this.finalizeTransformation();
+        const defaultSaveTargetChanges = () => {
+            this.targetDb.saveChanges();
+        };
+        await (options.saveTargetChanges ?? defaultSaveTargetChanges)(this);
     }
     /** Changeset data must be initialized in order to build correct changeOptions.
      * Call [[IModelTransformer.initialize]] for initialization of synchronization provenance data
      */
     getExportInitOpts(opts) {
-        if (!this._isSynchronization)
+        if (!this._options.argsForProcessChanges)
             return {};
+        const startChangeset = "startChangeset" in opts ? opts.startChangeset : undefined;
         return {
-            skipPropagateChangesToRootElements: this._options.skipPropagateChangesToRootElements ?? false,
-            accessToken: opts.accessToken,
+            skipPropagateChangesToRootElements: this._options.skipPropagateChangesToRootElements,
             ...(this._csFileProps
                 ? { csFileProps: this._csFileProps }
                 : this._changesetRanges
                     ? { changesetRanges: this._changesetRanges }
-                    : opts.startChangeset
-                        ? { startChangeset: opts.startChangeset }
+                    : startChangeset
+                        ? { startChangeset }
                         : {
                             startChangeset: {
                                 index: this.synchronizationVersion.index + 1,
@@ -2269,8 +2292,7 @@ class TemplateModelCloner extends IModelTransformer {
     }
     /** Cloning from a template requires this override of onTransformElement. */
     onTransformElement(sourceElement) {
-        // eslint-disable-next-line deprecation/deprecation
-        const referenceIds = sourceElement.getReferenceConcreteIds();
+        const referenceIds = sourceElement.getReferenceIds();
         referenceIds.forEach((referenceId) => {
             // TODO: consider going through all definition elements at once and remapping them to themselves
             if (!core_backend_1.EntityReferences.isValid(this.context.findTargetEntityId(referenceId))) {