@itwin/imodel-transformer 1.0.1-dev.0 → 1.1.0

package/lib/cjs/IModelTransformer.d.ts

@@ -1,11 +1,9 @@
-import { AccessToken, Id64Array, Id64String } from "@itwin/core-bentley";
+import { Id64Array, Id64Set, Id64String } from "@itwin/core-bentley";
 import * as ECSchemaMetaData from "@itwin/ecschema-metadata";
-import { Element, ElementAspect, ElementMultiAspect, ElementUniqueAspect, Entity, ExternalSourceAspect, IModelDb, Model, Relationship, RelationshipProps, SQLiteDb } from "@itwin/core-backend";
-import { ChangesetIndexAndId, CodeSpec, ElementAspectProps, ElementProps, EntityReference, EntityReferenceSet, ExternalSourceAspectProps, FontProps, ModelProps, Placement2d, Placement3d } from "@itwin/core-common";
-import { ExportChangesOptions, ExportSchemaResult, IModelExporter, IModelExportHandler } from "./IModelExporter";
+import { Element, ElementAspect, ElementMultiAspect, ElementUniqueAspect, Entity, ExternalSourceAspect, IModelDb, Model, Relationship, RelationshipProps } from "@itwin/core-backend";
+import { ChangesetIndexAndId, CodeSpec, ElementAspectProps, ElementProps, ExternalSourceAspectProps, FontProps, ModelProps, Placement2d, Placement3d } from "@itwin/core-common";
+import { ChangedInstanceIds, ExportChangesOptions, ExportSchemaResult, IModelExporter, IModelExportHandler } from "./IModelExporter";
 import { IModelImporter, OptimizeGeometryOptions } from "./IModelImporter";
-import { PendingReferenceMap } from "./PendingReferenceMap";
-import { EntityMap } from "./EntityMap";
 import { IModelCloneContext } from "./IModelCloneContext";
 /** Options provided to the [[IModelTransformer]] constructor.
  * @beta
@@ -18,7 +16,7 @@ export interface IModelTransformOptions {
      */
     targetScopeElementId?: Id64String;
     /** Set to `true` if IModelTransformer should not record its provenance.
-     * Provenance tracks a target element back to its corresponding source element and is essential for [[IModelTransformer.processChanges]] to work properly.
+     * Provenance tracks a target element back to its corresponding source element and is essential for [[IModelTransformer.process]] to work properly when [[IModelTransformOptions.argsForProcessChanges]] are provided.
      * Turning off IModelTransformer provenance is really only relevant for producing snapshots or another one time transformations.
      * @note See the [[includeSourceProvenance]] option for determining whether existing source provenance is cloned into the target.
      * @note The default is `false` which means that new IModelTransformer provenance will be recorded.
@@ -35,13 +33,6 @@ export interface IModelTransformOptions {
      * @note This *hint* is typically only set for the first synchronization after the iModel was copied since every other synchronization can utilize the provenance.
      */
     wasSourceIModelCopiedToTarget?: boolean;
-    /** Flag that indicates that the current source and target iModels are now synchronizing in the reverse direction from a prior synchronization.
-     * The most common example is to first synchronize master to branch, make changes to the branch, and then reverse directions to synchronize from branch to master.
-     * This means that the provenance on the (current) source is used instead.
-     * @note This also means that only [[IModelTransformer.processChanges]] can detect deletes.
-     * @deprecated in 1.x this option is ignored and the transformer now detects synchronization direction using the target scope element
-     */
-    isReverseSynchronization?: boolean;
     /** Flag that indicates whether or not the transformation process needs to consider the source geometry before cloning/transforming.
      * For standard cases, it is not required to load the source GeometryStream in JavaScript since the cloning happens in native code.
      * Also, the target GeometryStream will be available in JavaScript prior to insert.
@@ -70,20 +61,6 @@ export interface IModelTransformOptions {
      * @beta
      */
     preserveElementIdsForFiltering?: boolean;
-    /** The behavior to use when an element reference (id) is found stored as a reference on an element in the source,
-     * but the referenced element does not actually exist in the source.
-     * It is possible to craft an iModel with dangling references/invalidated relationships by, e.g., deleting certain
-     * elements without fixing up references.
-     *
-     * @note "reject" will throw an error and reject the transformation upon finding this case.
-     * @note "ignore" passes the issue down to consuming applications, iModels that have invalid element references
-     *       like this can cause errors, and you should consider adding custom logic in your transformer to remove the
-     *       reference depending on your use case.
-     * @default "reject"
-     * @beta
-     * @deprecated in 3.x. use [[danglingReferencesBehavior]] instead, the use of the term *predecessors* was confusing and became inaccurate when the transformer could handle cycles
-     */
-    danglingPredecessorsBehavior?: "reject" | "ignore";
     /** The behavior to use when an element reference (id) is found stored as a reference on an element in the source,
      * but the referenced element does not actually exist in the source.
      * It is possible to craft an iModel with dangling references/invalidated relationships by, e.g., deleting certain
@@ -97,7 +74,7 @@ export interface IModelTransformOptions {
      * @beta
      */
     danglingReferencesBehavior?: "reject" | "ignore";
-    /** If defined, options to be supplied to [[IModelImporter.optimizeGeometry]] by [[IModelTransformer.processChanges]] and [[IModelTransformer.processAll]]
+    /** If defined, options to be supplied to [[IModelImporter.optimizeGeometry]] by [[IModelTransformer.process]]
      * as a post-processing step to optimize the geometry in the iModel.
      * @beta
      */
@@ -117,13 +94,6 @@ export interface IModelTransformOptions {
      * @default false
      */
     noDetachChangeCache?: boolean;
-    /**
-     * Do not check that processChanges is called from the next changeset index.
-     * This is an unsafe option (e.g. it can cause data loss in future branch operations)
-     * and you should not use it.
-     * @default false
-     */
-    ignoreMissingChangesetsInSynchronizations?: boolean;
     /**
      * Do not error out if a scoping ESA @see ExternalSourceAspectProps is found without a version or jsonProperties defined on that scoping ESA.
      * If true, the version and jsonproperties will be properly set on the scoping ESA @see TargetScopeProvenanceJsonProps after the transformer is complete.
@@ -135,31 +105,15 @@ export interface IModelTransformOptions {
     branchRelationshipDataBehavior?: "unsafe-migrate" | "reject";
     /**
      * Skip propagating changes made to the root subject, dictionaryModel and IModelImporter._realityDataSourceLinkPartitionStaticId (0xe)
-     * @default false
+     * If it is set to false, changes to root elements are propagated, the root subject name gets changed and leads to the iModelDb.name property being updated in .initializeiModelDb
+     * @default true
      */
     skipPropagateChangesToRootElements?: boolean;
-}
-/**
- * A container for tracking the state of a partially committed entity and finalizing it when it's ready to be fully committed
- * @internal
- */
-declare class PartiallyCommittedEntity {
     /**
-     * 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
+     * Arguments to use for the processing of changes. The args being defined or not defined will influence the behavior of @see [[IModelTransformer.process]].
+     * @default undefined
      */
-    private _missingReferences;
-    private _onComplete;
-    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: EntityReferenceSet, _onComplete: () => void);
-    resolveReference(id: EntityReference): void;
-    forceComplete(): void;
+    argsForProcessChanges?: ProcessChangesOptions;
 }
 /**
  * Data type for persisting change version information within provenance Scope ExternalSourceAspect.
@@ -186,7 +140,6 @@ export interface TargetScopeProvenanceJsonProps {
  * @beta
  */
 export interface InitOptions {
-    accessToken?: AccessToken;
     /**
      * Include changes from this changeset up through and including the current changeset.
      * @note To form a range of versions to process, set `startChangeset` for the start (inclusive)
@@ -199,41 +152,41 @@ export interface InitOptions {
     };
 }
 /**
- * Arguments for [[IModelTransformer.processChanges]]
- */
-export type ProcessChangesOptions = ExportChangesOptions & FinalizeTransformationOptions;
-/**
- * Options which modify the behavior of [[IModelTransformer.finalizeTransformation]], called at the end of [[IModelTransformer.processAll]] and [[IModelTransformer.processChanges]].
+ * Arguments used during [[IModelTransformer.process]] if provided in [[IModelTransformOptions.argsForProcessChanges]].
  * @beta
  */
-export interface FinalizeTransformationOptions {
-    /**
-     * This description will be used when the transformer needs to push changes to the branch during a reverse sync.
-     * @default `Update provenance in response to a reverse sync to iModel: ${this.targetDb.iModelId}`
-     */
-    reverseSyncBranchChangesetDescription?: string;
+export type ProcessChangesOptions = ExportChangesOptions & {
+    /** how to call saveChanges on the target. Must call targetDb.saveChanges, should not edit the iModel */
+    saveTargetChanges?: (transformer: IModelTransformer) => Promise<void>;
     /**
-     * This description will be used when the transformer needs to push changes to master during a reverse sync.
-     * @default `Reverse sync of iModel: ${this.sourceDb.iModelId}`
+     * The forward sync 'version' to set on the scoping ESA @see ExternalSourceAspectProps upon startup, if the version property on the scoping ESA is undefined or empty string.
+     * @note This option is not without risk! You must also set @see branchRelationshipDataBehavior to "unsafe-migrate".
+     * @note This value is ignored if the version property on the scoping ESA is NOT undefined or empty string.
+     * @default ""
      */
-    reverseSyncMasterChangesetDescription?: string;
+    unsafeFallbackSyncVersion?: string;
     /**
-     * This description will be used when the transformer needs to push changes to the branch during a forward sync.
-     * @default `Forward sync of iModel: ${this.sourceDb.iModelId}`
+     * The reverse sync version to set on the scoping ESA @see TargetScopeProvenanceJsonProps upon startup, if the reverseSync property on the scoping ESA is undefined or empty string.
+     * @note This option is not without risk! You must also set @see branchRelationshipDataBehavior to "unsafe-migrate".
+     * @note This value is ignored if the reverseSyncVersion property on the scoping ESA is NOT undefined or empty string.
+     * @default ""
      */
-    forwardSyncBranchChangesetDescription?: string;
+    unsafeFallbackReverseSyncVersion?: string;
     /**
-     * This description will be used when the transformer needs to push changes to the branch during a provenance init transform.
-     * @default `initialized branch provenance with master iModel: ${this.sourceDb.iModelId}`
+     * Do not check that process (with [[IModelTransformOptions.argsForProcessChanges]] provided) is called from the next changeset index.
+     * This is an unsafe option (e.g. it can cause data loss in future branch operations)
+     * and you should not use it.
+     * @default false
      */
-    provenanceInitTransformChangesetDescription?: string;
-    /** how to call saveChanges on the target. Must call targetDb.saveChanges, should not edit the iModel */
-    saveTargetChanges?: (transformer: IModelTransformer) => Promise<void>;
-}
-/** Arguments you can pass to [[IModelTransformer.initExternalSourceAspects]]
- * @deprecated in 0.1.0. Use [[InitOptions]] (and [[IModelTransformer.initialize]]) instead.
+    ignoreMissingChangesetsInSynchronizations?: boolean;
+};
+/**
+ * @beta
  */
-export type InitFromExternalSourceAspectsArgs = InitOptions;
+export interface RelationshipPropsForDelete {
+    id: Id64String;
+    classFullName: string;
+}
 /** Base class used to transform a source iModel into a different target iModel.
  * @see [iModel Transformation and Data Exchange]($docs/learning/transformer/index.md), [IModelExporter]($transformer), [IModelImporter]($transformer)
  * @beta
@@ -254,16 +207,14 @@ export declare class IModelTransformer extends IModelExportHandler {
     private _syncType?;
     /** The Id of the Element in the **target** iModel that represents the **source** repository as a whole and scopes its [ExternalSourceAspect]($backend) instances. */
     get targetScopeElementId(): Id64String;
-    /** 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 */
-    protected _pendingReferences: PendingReferenceMap<PartiallyCommittedEntity>;
     /** a set of elements for which source provenance will be explicitly tracked by ExternalSourceAspects */
     protected _elementsWithExplicitlyTrackedProvenance: Set<string>;
-    /** map of partially committed entities to their partial commit progress */
-    protected _partiallyCommittedEntities: EntityMap<PartiallyCommittedEntity>;
+    protected _partiallyCommittedElementIds: Id64Set;
+    protected _partiallyCommittedAspectIds: Id64Set;
     /** the options that were used to initialize this transformer */
     private readonly _options;
-    private _isSynchronization;
+    /** @see hasDefinitionContainerDeletionFeature */
+    private _hasDefinitionContainerDeletionFeature?;
     /**
      * 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.
@@ -306,10 +257,6 @@ export declare class IModelTransformer extends IModelExportHandler {
     static get provenanceElementClasses(): (typeof Entity)[];
     /** The element aspect classes that are considered to define provenance in the iModel */
     static get provenanceElementAspectClasses(): (typeof Entity)[];
-    /** 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.
-     */
-    protected _skippedEntities: Set<`m${string}` | `e${string}` | `a${string}` | `r${string}`>;
     /** Construct a new IModelTransformer
      * @param source Specifies the source IModelExporter or the source IModelDb that will be used to construct the source IModelExporter.
      * @param target Specifies the target IModelImporter or the target IModelDb that will be used to construct the target IModelImporter.
@@ -369,17 +316,23 @@ export declare class IModelTransformer extends IModelExportHandler {
      */
     private _startingChangesetIndices;
     private _cachedSynchronizationVersion;
-    /** the changeset in the scoping element's source version found for this transformation
-     * @note: the version depends on whether this is a reverse synchronization or not, as
-     * it is stored separately for both synchronization directions.
-     * @note: must call [[initScopeProvenance]] before using this property.
-     * @note: empty string and -1 for changeset and index if it has never been transformed or was transformed before federation guid update (pre 1.x).
+    /**
+     * As of itwinjs 4.6.0, definitionContainers are now deleted as if they were DefinitionPartitions as opposed to Definitions.
+     * This variable being true will be used to special case the deletion of DefinitionContainers the same way DefinitionPartitions are deleted.
+     */
+    protected get hasDefinitionContainerDeletionFeature(): boolean;
+    /**
+     * We cache the synchronization version to avoid querying the target scoping ESA multiple times.
+     * If the target scoping ESA is ever updated we need to clear any potentially cached sync version otherwise we will get stale values.
+     * Sets this._cachedSynchronizationVersion to undefined.
      */
-    private get _synchronizationVersion();
+    private clearCachedSynchronizationVersion;
     /** the changeset in the scoping element's source version found for this transformation
-     * @note: the version depends on whether this is a reverse synchronization or not, as
+     * @note the version depends on whether this is a reverse synchronization or not, as
      * it is stored separately for both synchronization directions.
-     * @note: empty string and -1 for changeset and index if it has never been transformed, or was transformed before federation guid update (pre 1.x).
+     * @note empty string and -1 for changeset and index if it has never been transformed
+     * @note empty string and -1 for changeset and index if it was transformed before federation guid update (pre 1.x) and @see [[IModelTransformOptions.branchRelationshipDataBehavior]] === "unsafe-migrate".
+     * @throws if the version is not found in a preexisting scope aspect and @see [[IModelTransformOptions.branchRelationshipDataBehavior]] !== "unsafe-migrate"
      */
     protected get synchronizationVersion(): ChangesetIndexAndId;
     /**
@@ -394,6 +347,8 @@ export declare class IModelTransformer extends IModelExportHandler {
      *          if this was a [BriefcaseDb]($backend)
      */
     protected initScopeProvenance(): void;
+    /** Returns true if a change was made to the aspectProps. */
+    private handleUnsafeMigrate;
     /**
      * Iterate all matching federation guids and ExternalSourceAspects in the provenance iModel (target unless reverse sync)
      * and call a function for each one.
@@ -409,7 +364,21 @@ export declare class IModelTransformer extends IModelExportHandler {
         skipPropagateChangesToRootElements: boolean;
     }): void;
     private forEachTrackedElement;
+    /**
+     * Queries the provenanceDb for an ESA whose identifier is equal to the provided 'entityInProvenanceSourceId'.
+     * The identifier on the ESA is the id of the element in the [[IModelTransformer.provenanceSourceDb]]
+     * Therefore it only makes sense to call this function when you have an id in the provenanceSourceDb.
+     * @param entityInProvenanceSourceId
+     * @returns the elementId that the ESA is stored on, esa.Element.Id
+     */
     private _queryProvenanceForElement;
+    /**
+     * Queries the provenanceDb for an ESA whose identifier is equal to the provided 'entityInProvenanceSourceId'.
+     * The identifier on the ESA is the id of the relationship in the [[IModelTransformer.provenanceSourceDb]]
+     * Therefore it only makes sense to call this function when you have an id in the provenanceSourceDb.
+     * @param entityInProvenanceSourceId
+     * @returns
+     */
     private _queryProvenanceForRelationship;
     private _queryTargetRelId;
     private _targetClassNameToClassIdCache;
@@ -418,24 +387,20 @@ export declare class IModelTransformer extends IModelExportHandler {
     private _queryElemIdByFedGuid;
     /** 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.
      */
     protected shouldDetectDeletes(): boolean;
     /**
      * 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.
      */
     detectElementDeletes(): Promise<void>;
-    /**
-     * @deprecated in 3.x, this no longer has any effect except emitting a warning
-     */
-    protected skipElement(_sourceElement: Element): void;
     /** 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.
@@ -443,38 +408,30 @@ export declare class IModelTransformer extends IModelExportHandler {
      * @note This can be called more than once for an element in arbitrary order, so it should not have side-effects.
      */
     onTransformElement(sourceElement: Element): ElementProps;
-    private _hasElementChangedCache?;
     private _deletedSourceRelationshipData?;
     /** Returns true if a change within sourceElement is detected.
      * @param sourceElement The Element from the source iModel
-     * @param targetElementId The Element from the target iModel to compare against.
      * @note A subclass can override this method to provide custom change detection behavior.
      */
-    protected hasElementChanged(sourceElement: Element, _targetElementId: Id64String): boolean;
-    private static transformCallbackFor;
-    /** 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
-     */
-    private makePartialEntityCompleter;
-    /** 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
-     */
-    private collectUnmappedReferences;
+    protected hasElementChanged(sourceElement: Element): boolean;
+    protected completePartiallyCommittedElements(): void;
+    protected completePartiallyCommittedAspects(): void;
+    private doAllReferencesExistInTarget;
+    private assertReferenceExistsInSource;
     /** 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.
      */
     processElement(sourceElementId: Id64String): Promise<void>;
     /** 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.
      */
     processChildElements(sourceElementId: Id64String): Promise<void>;
     /** Override of [IModelExportHandler.shouldExportElement]($transformer) that is called to determine if an element should be exported from the source iModel.
      * @note Reaching this point means that the element has passed the standard exclusion checks in IModelExporter.
      */
     shouldExportElement(_sourceElement: Element): boolean;
-    onSkipElement(sourceElementId: Id64String): void;
     /**
      * If they haven't been already, import all of the required references
      * @internal do not call, override or implement this, it will be removed
@@ -485,7 +442,6 @@ export declare class IModelTransformer extends IModelExportHandler {
      * This override calls [[onTransformElement]] and then [IModelImporter.importElement]($transformer) to update the target iModel.
      */
     onExportElement(sourceElement: Element): void;
-    private resolvePendingReferences;
     /** 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).
      */
@@ -500,14 +456,14 @@ export declare class IModelTransformer extends IModelExportHandler {
     private scheduleModeledPartitionDeletion;
     /** 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.
      */
     processModel(sourceModeledElementId: Id64String): Promise<void>;
     /** Cause the model contents to be exported from the source iModel and imported into the target iModel.
      * @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.
      */
     processModelContents(sourceModelId: Id64String, targetModelId: Id64String, elementClassFullName?: string): Promise<void>;
     /** Cause all sub-models that recursively descend from the specified Subject to be exported from the source iModel and imported into the target iModel. */
@@ -519,27 +475,31 @@ export declare class IModelTransformer extends IModelExportHandler {
      * @note A subclass can override this method to provide custom transform behavior.
      */
     onTransformModel(sourceModel: Model, targetModeledElementId: Id64String): ModelProps;
-    /** 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
-     */
-    processDeferredElements(_numRetries?: number): Promise<void>;
-    /** called at the end ([[finalizeTransformation]]) 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 }?: {
-        force?: boolean | undefined;
+    updateSynchronizationVersion({ initializeReverseSyncVersion, }?: {
+        initializeReverseSyncVersion?: boolean | undefined;
     }): void;
     private finalizeTransformation;
     /** 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.
      */
     processRelationships(baseRelClassFullName: string): Promise<void>;
     /** Override of [IModelExportHandler.shouldExportRelationship]($transformer) that is called to determine if a [Relationship]($backend) should be exported.
@@ -557,8 +517,8 @@ export declare class IModelTransformer extends IModelExportHandler {
     private _yieldManager;
     /** 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.
      */
     detectRelationshipDeletes(): Promise<void>;
@@ -580,11 +540,10 @@ export declare class IModelTransformer extends IModelExportHandler {
     onExportElementMultiAspects(sourceAspects: ElementMultiAspect[]): void;
     /** 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.
      */
-    protected onTransformElementAspect(sourceElementAspect: ElementAspect, _targetElementId: Id64String): ElementAspectProps;
+    protected onTransformElementAspect(sourceElementAspect: ElementAspect): ElementAspectProps;
     /** The directory where schemas will be exported, a random temporary directory */
     protected _schemaExportDir: string;
     /** Override of [IModelExportHandler.shouldExportSchema]($transformer) that is called to determine if a schema should be exported
@@ -608,17 +567,17 @@ export declare class IModelTransformer extends IModelExportHandler {
      */
     processSchemas(): Promise<void>;
     /** 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.
      */
     processFonts(): Promise<void>;
     /** Override of [IModelExportHandler.onExportFont]($transformer) that imports a font into the target iModel when it is exported from the source iModel. */
     onExportFont(font: FontProps, _isUpdate: boolean | undefined): void;
     /** 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.
      */
     processCodeSpecs(): Promise<void>;
     /** 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.
      */
     processCodeSpec(codeSpecName: string): Promise<void>;
     /** Override of [IModelExportHandler.shouldExportCodeSpec]($transformer) that is called to determine if a CodeSpec should be exported from the source iModel.
@@ -636,19 +595,27 @@ export declare class IModelTransformer extends IModelExportHandler {
     private _csFileProps?;
     /**
      * 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
      */
-    initialize(args?: InitOptions): Promise<void>;
+    initialize(): Promise<void>;
     /**
-     * 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.
-     * Populates this._hasElementChangedCache with a set of elementIds that have been updated or inserted into the database.
+     * Reads all the changeset files in the private member of the transformer: _csFileProps
+     * and finds the corresponding target entity for any deleted source entities and remaps the sourceId to the targetId.
      * This function returns early if csFileProps is undefined or is of length 0.
      * @returns void
      */
     private processChangesets;
+    /**
+     * This will be called when transformer is called with [[IModelTransformOptions.argsForProcessChanges]] to process changes.
+     * It will be executed after changes in changesets are populated into `sourceDbChanges` and before data processing begins.
+     * Remap table between the source and target iModels will be built at that time, meaning that functions like [[IModelTransformer.context.findTargetElementId]] will return meaningful results.
+     * This function should be used to modify the `sourceDbChanges`, if necessary, using `add custom change` methods in [[ChangedInstanceIds]], such as [[ChangedInstanceIds.addCustomElementChange]], [[ChangedInstanceIds.addCustomModelChange]] and other.
+     * @param sourceDbChanges the ChangedInstanceIds already populated by the exporter with the changes in source changesets, if any, passed to the transformer.
+     * @note Its expected that this function be overridden by a subclass of transformer if it needs to modify sourceDbChanges.
+     */
+    protected addCustomChanges(_sourceDbChanges: ChangedInstanceIds): Promise<void>;
     /**
      * 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"
@@ -661,77 +628,47 @@ export declare class IModelTransformer extends IModelExportHandler {
      */
     private processDeletedOp;
     private _tryInitChangesetData;
+    /**
+     * 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.
+     *
+     */
+    process(): Promise<void>;
     /** 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.
      */
-    processAll(options?: FinalizeTransformationOptions): Promise<void>;
+    private processAll;
     /** previous provenance, either a federation guid, a `${sourceFedGuid}/${targetFedGuid}` pair, or required aspect props */
     private _lastProvenanceEntityInfo;
     private markLastProvenance;
-    /** @internal the name of the table where javascript state of the transformer is serialized in transformer state dumps */
-    static readonly jsStateTable = "TransformerJsState";
-    /** @internal the name of the table where the target state heuristics is serialized in transformer state dumps */
-    static readonly lastProvenanceEntityInfoTable = "LastProvenanceEntityInfo";
-    /**
-     * Load the state of the active transformation from an open SQLiteDb
-     * You can override this if you'd like to load from custom tables in the resumable dump state, but you should call
-     * this super implementation
-     * @note the SQLiteDb must be open
-     */
-    protected loadStateFromDb(db: SQLiteDb): void;
-    /**
-     * @deprecated in 0.1.x, this is buggy, and it is now equivalently efficient to simply restart the transformation
-     * from the original changeset
-     *
-     * Return a new transformer instance with the same remappings state as saved from a previous [[IModelTransformer.saveStateToFile]] call.
-     * This allows you to "resume" an iModel transformation, you will have to call [[IModelTransformer.processChanges]]/[[IModelTransformer.processAll]]
-     * again but the remapping state will cause already mapped elements to be skipped.
-     * To "resume" an iModel Transformation you need:
-     * - the sourceDb at the same changeset
-     * - the same targetDb in the state in which it was before
-     * @param statePath the path to the serialized state of the transformer, use [[IModelTransformer.saveStateToFile]] to get this from an existing transformer instance
-     * @param constructorArgs remaining arguments that you would normally pass to the Transformer subclass you are using, usually (sourceDb, targetDb)
-     * @note custom transformers with custom state may need to override this method in order to handle loading their own custom state somewhere
-     */
-    static resumeTransformation<SubClass extends new (...a: any[]) => IModelTransformer = typeof IModelTransformer>(this: SubClass, statePath: string, ...constructorArgs: ConstructorParameters<SubClass>): InstanceType<SubClass>;
-    /**
-     * You may override this to store arbitrary json state in a transformer state dump, useful for some resumptions
-     * @see [[IModelTransformer.saveStateToFile]]
-     */
-    protected getAdditionalStateJson(): any;
-    /**
-     * You may override this to load arbitrary json state in a transformer state dump, useful for some resumptions
-     * @see [[IModelTransformer.loadStateFromFile]]
-     */
-    protected loadAdditionalStateJson(_additionalState: any): void;
-    /**
-     * Save the state of the active transformation to an open SQLiteDb
-     * You can override this if you'd like to write custom tables to the resumable dump state, but you should call
-     * this super implementation
-     * @note the SQLiteDb must be open
-     */
-    protected saveStateToDb(db: SQLiteDb): void;
-    /**
-     * @deprecated in 0.1.x, this is buggy, and it is now equivalently efficient to simply restart the transformation
-     * from the original changeset
-     *
-     * Save the state of the active transformation to a file path, if a file at the path already exists, it will be overwritten
-     * This state can be used by [[IModelTransformer.resumeTransformation]] to resume a transformation from this point.
-     * The serialization format is a custom sqlite database.
-     * @note custom transformers with custom state may override [[IModelTransformer.saveStateToDb]] or [[IModelTransformer.getAdditionalStateJson]]
-     *       and [[IModelTransformer.loadStateFromDb]] (with a super call) or [[IModelTransformer.loadAdditionalStateJson]]
-     *       if they have custom state that needs to be stored with
-     *       potentially inside the same sqlite file in separate tables
-     */
-    saveStateToFile(nativeStatePath: string): void;
     /** 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.
      */
-    processChanges(options: ProcessChangesOptions): Promise<void>;
+    private processChanges;
     /** Changeset data must be initialized in order to build correct changeOptions.
      * Call [[IModelTransformer.initialize]] for initialization of synchronization provenance data
      */
@@ -777,5 +714,4 @@ export declare class TemplateModelCloner extends IModelTransformer {
     /** Cloning from a template requires this override of onTransformElement. */
     onTransformElement(sourceElement: Element): ElementProps;
 }
-export {};
 //# sourceMappingURL=IModelTransformer.d.ts.map