@itwin/imodel-transformer 1.0.0-dev.13 → 1.0.0-dev.14

package/lib/cjs/IModelTransformer.js

@@ -172,7 +172,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         if (this._isProvenanceInitTransform) {
             return "forward";
         }
-        if (!this._isSynchronization) {
+        if (!this._options.argsForProcessChanges) {
             return "not-sync";
         }
         try {
@@ -224,7 +224,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         this._elementsWithExplicitlyTrackedProvenance = new Set();
         /** map of partially committed entities to their partial commit progress */
         this._partiallyCommittedEntities = new EntityMap_1.EntityMap();
-        this._isSynchronization = false;
         /**
          * 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.
@@ -278,6 +277,10 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             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
@@ -361,9 +364,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}`);
     }
@@ -606,8 +606,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)) {
@@ -867,7 +868,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);
@@ -877,9 +878,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.
      */
@@ -1037,7 +1038,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     }
     /** 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();
@@ -1048,7 +1049,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();
@@ -1333,7 +1334,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();
@@ -1343,7 +1344,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();
@@ -1409,9 +1410,9 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * 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
+     * @note if [[IModelTransformOptions.argsForProcessChanges]] are not defined in this transformation, this will fail
      * without setting the `force` option to `true`
      */
     updateSynchronizationVersion({ force = false } = {}) {
@@ -1438,7 +1439,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             core_bentley_1.Logger.logInfo(loggerCategory, `updating sync version from ${this._targetScopeProvenanceProps.version} to ${sourceVersion}`);
             this._targetScopeProvenanceProps.version = sourceVersion;
         }
-        if (this._isSynchronization ||
+        if (this._options.argsForProcessChanges ||
             (this._startingChangesetIndices && this._isProvenanceInitTransform)) {
             nodeAssert(this.targetDb.changeset.index !== undefined &&
                 this._startingChangesetIndices !== undefined, "updateSynchronizationVersion was called without change history");
@@ -1515,7 +1516,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     }
     /** 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();
@@ -1588,8 +1589,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() {
@@ -1771,7 +1772,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
@@ -1783,14 +1784,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();
@@ -1818,17 +1819,18 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     }
     /**
      * 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;
@@ -2037,10 +2039,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"
@@ -2050,11 +2053,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" : ""},` +
@@ -2089,13 +2092,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() {
-        this.logSettings();
-        this.initScopeProvenance();
-        await this.initialize();
         await this.exporter.exportCodeSpecs();
         await this.exporter.exportFonts();
         if (this._options.skipPropagateChangesToRootElements) {
@@ -2145,10 +2175,6 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * @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
@@ -2165,17 +2191,17 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
      * 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,
-            accessToken: opts.accessToken,
             ...(this._csFileProps
                 ? { csFileProps: this._csFileProps }
                 : this._changesetRanges
                     ? { changesetRanges: this._changesetRanges }
-                    : opts.startChangeset
-                        ? { startChangeset: opts.startChangeset }
+                    : startChangeset
+                        ? { startChangeset }
                         : {
                             startChangeset: {
                                 index: this.synchronizationVersion.index + 1,