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

package/lib/cjs/IModelExporter.js

@@ -55,7 +55,9 @@ class IModelExportHandler {
     shouldExportElement(_element) {
         return true;
     }
-    /** Called when element is skipped instead of exported. */
+    /** Called when element is skipped instead of exported.
+     * @note When an element is skipped, exporter will not export any of its child elements. Because of this, [[onSkipElement]] will not be invoked for any children of a "skipped" element.
+     */
     onSkipElement(_elementId) { }
     /** Called when an element should be exported.
      * @param element The element to export
@@ -130,7 +132,7 @@ exports.IModelExportHandler = IModelExportHandler;
 class IModelExporter {
     /**
      * Retrieve the cached entity change information.
-     * @note This will only be initialized after [IModelExporter.exportChanges] is invoked.
+     * @note This will only be initialized after [IModelExporter.exportChanges] is invoked or [IModelExporter.initialize] is called.
      */
     get sourceDbChanges() {
         return this._sourceDbChanges;
@@ -214,6 +216,16 @@ class IModelExporter {
             return;
         this._exportElementAspectsStrategy.setAspectChanges(this._sourceDbChanges.aspect);
     }
+    /**
+     * This function is called by the transformer as it is about to process the changesets passed to it in [[IModelTransformOptions.argsForProcessChanges]].
+     * This would be after the exporter has already processed the same set of changesets passed to the transformer in [[IModelTransformOptions.argsForProcessChanges]].
+     * This function should be used to modify the exporter's sourceDbChanges, if necessary, using [[ChangedInstanceIds.addCustomChange]]. See [[ChangedInstanceIds.addCustomChange]] for more information.
+     * @note [[IModelExporter.sourceDbChanges]] will only be defined if the transformer was called with [[IModelTransformOptions.argsForProcessChanges]].
+     * @note If defined, sourceDbChanges will already be populated with the changesets passed to the transformer, if any when this function is called by the transformer.
+     * @note The transformer will have built up the remap table between the source and target iModels before calling this function. This means that functions like [[IModelTransformer.context.findTargetElementId]] will return meaningful results.
+     * @note Its expected that this function be overridden by a subclass of exporter if it needs to modify sourceDbChanges.
+     */
+    addCustomChanges() { }
     /** Register the handler that will be called by IModelExporter. */
     registerHandler(handler) {
         this._handler = handler;
@@ -252,19 +264,25 @@ class IModelExporter {
         await this.exportModel(core_common_1.IModel.repositoryModelId);
         await this.exportRelationships(core_backend_1.ElementRefersToElements.classFullName);
     }
-    async exportChanges(accessTokenOrOpts, startChangesetId) {
+    /** Export changes from the source iModel.
+     * Inserts, updates, and deletes are determined by inspecting the changeset(s).
+     * @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.
+     * @note the changedInstanceIds are just for this call to exportChanges, so you must continue to pass it in
+     *       for consecutive calls
+     */
+    async exportChanges(args) {
         if (!this.sourceDb.isBriefcaseDb())
             throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Must be a briefcase to export changes");
         if ("" === this.sourceDb.changeset.id) {
             await this.exportAll(); // no changesets, so revert to exportAll
             return;
         }
-        const initOpts = typeof accessTokenOrOpts === "object"
-            ? accessTokenOrOpts
-            : {
-                accessToken: accessTokenOrOpts,
-                startChangeset: { id: startChangesetId },
-            };
+        const startChangeset = // TODO: This is weird.. why is this needed? I suspect we can remove this and just pass args to initialize?
+         args && "startChangeset" in args ? args.startChangeset : undefined;
+        const initOpts = {
+            startChangeset: { id: startChangeset?.id },
+        };
         await this.initialize(initOpts);
         // _sourceDbChanges are initialized in this.initialize
         nodeAssert(this._sourceDbChanges !== undefined, "sourceDbChanges must be initialized.");
@@ -377,7 +395,7 @@ class IModelExporter {
     async exportCodeSpecByName(codeSpecName) {
         const codeSpec = this.sourceDb.codeSpecs.getByName(codeSpecName);
         let isUpdate;
-        if (undefined !== this._sourceDbChanges) {
+        if (this._sourceDbChanges !== undefined) {
             // is changeset information available?
             if (this._sourceDbChanges.codeSpec.insertIds.has(codeSpec.id)) {
                 isUpdate = false;
@@ -469,7 +487,7 @@ class IModelExporter {
     /** Export the model (the container only) from the source iModel. */
     async exportModelContainer(model) {
         let isUpdate;
-        if (undefined !== this._sourceDbChanges) {
+        if (this._sourceDbChanges !== undefined) {
             // is changeset information available?
             if (this._sourceDbChanges.model.insertIds.has(model.id)) {
                 isUpdate = false;
@@ -500,7 +518,7 @@ class IModelExporter {
             core_bentley_1.Logger.logTrace(loggerCategory, `visitElements=false, skipping exportModelContents(${modelId})`);
             return;
         }
-        if (undefined !== this._sourceDbChanges) {
+        if (this._sourceDbChanges !== undefined) {
             // is changeset information available?
             if (!this._sourceDbChanges.model.insertIds.has(modelId) &&
                 !this._sourceDbChanges.model.updateIds.has(modelId)) {
@@ -674,7 +692,7 @@ class IModelExporter {
             return;
         }
         let isUpdate;
-        if (undefined !== this._sourceDbChanges) {
+        if (this._sourceDbChanges !== undefined) {
             // is changeset information available?
             if (this._sourceDbChanges.relationship.insertIds.has(relInstanceId)) {
                 isUpdate = false;
@@ -711,7 +729,7 @@ class IModelExporter {
 }
 exports.IModelExporter = IModelExporter;
 /** Class for holding change information.
- * @beta
+ * @public
  */
 class ChangedInstanceOps {
     constructor() {
@@ -730,11 +748,16 @@ class ChangedInstanceOps {
                 val.delete.forEach((id) => this.deleteIds.add(id));
         }
     }
+    get isEmpty() {
+        return (0 === this.insertIds.size &&
+            0 === this.updateIds.size &&
+            0 === this.deleteIds.size);
+    }
 }
 exports.ChangedInstanceOps = ChangedInstanceOps;
 /**
  * Class for discovering modified elements between 2 versions of an iModel.
- * @beta
+ * @public
  */
 class ChangedInstanceIds {
     constructor(db) {
@@ -745,6 +768,8 @@ class ChangedInstanceIds {
         this.relationship = new ChangedInstanceOps();
         this.font = new ChangedInstanceOps();
         this._db = db;
+        this._hasCustomChanges = false;
+        this._entityReferenceToCustomDataMap = new Map();
     }
     async setupECClassIds() {
         this._codeSpecSubclassIds = new Set();
@@ -752,9 +777,12 @@ class ChangedInstanceIds {
         this._elementSubclassIds = new Set();
         this._aspectSubclassIds = new Set();
         this._relationshipSubclassIds = new Set();
+        this._relationshipSubclassIdsToSkip = new Set();
+        this._ecClassIdsToClassFullNames = new Map();
         const addECClassIdsToSet = async (setToModify, baseClass) => {
-            for await (const row of this._db.createQueryReader(`SELECT ECInstanceId FROM ECDbMeta.ECClassDef where ECInstanceId IS (${baseClass})`)) {
-                setToModify.add(row.ECInstanceId);
+            for await (const row of this._db.createQueryReader(`SELECT c.ECInstanceId ECClassId, c.Name className, s.Name schemaName FROM ECDbMeta.ECClassDef c JOIN ECDbMeta.ECSchemaDef s ON s.ECInstanceId = c.Schema.Id WHERE c.ECInstanceId IS (${baseClass})`)) {
+                setToModify.add(row.ECClassId);
+                this._ecClassIdsToClassFullNames?.set(row.ECClassId, `${row.schemaName}:${row.className}`);
             }
         };
         const promises = [
@@ -764,6 +792,7 @@ class ChangedInstanceIds {
             addECClassIdsToSet(this._aspectSubclassIds, "BisCore.ElementUniqueAspect"),
             addECClassIdsToSet(this._aspectSubclassIds, "BisCore.ElementMultiAspect"),
             addECClassIdsToSet(this._relationshipSubclassIds, "BisCore.ElementRefersToElements"),
+            addECClassIdsToSet(this._relationshipSubclassIdsToSkip, "BisCore.ElementDrivesElement"),
         ];
         await Promise.all(promises);
     }
@@ -772,7 +801,8 @@ class ChangedInstanceIds {
             this._modelSubclassIds &&
             this._elementSubclassIds &&
             this._aspectSubclassIds &&
-            this._relationshipSubclassIds);
+            this._relationshipSubclassIds &&
+            this._relationshipSubclassIdsToSkip);
     }
     isRelationship(ecClassId) {
         return this._relationshipSubclassIds?.has(ecClassId);
@@ -789,6 +819,17 @@ class ChangedInstanceIds {
     isElement(ecClassId) {
         return this._elementSubclassIds?.has(ecClassId);
     }
+    get hasCustomChanges() {
+        return this._hasCustomChanges;
+    }
+    get isEmpty() {
+        return (this.codeSpec.isEmpty &&
+            this.model.isEmpty &&
+            this.element.isEmpty &&
+            this.aspect.isEmpty &&
+            this.relationship.isEmpty &&
+            this.font.isEmpty);
+    }
     /**
      * Adds the provided [[ChangedECInstance]] to the appropriate set of changes by class type (codeSpec, model, element, aspect, or relationship) maintained by this instance of ChangedInstanceIds.
      * If the same ECInstanceId is seen multiple times, the changedInstanceIds will be modified accordingly, i.e. if an id 'x' was updated but now we see 'x' was deleted, we will remove 'x'
@@ -804,6 +845,8 @@ class ChangedInstanceIds {
         const changeType = change.$meta?.op;
         if (changeType === undefined)
             throw new Error(`ChangeType was undefined for id: ${change.ECInstanceId}.`);
+        if (this._relationshipSubclassIdsToSkip?.has(ecClassId))
+            return;
         if (this.isRelationship(ecClassId))
             this.handleChange(this.relationship, changeType, change.ECInstanceId);
         else if (this.isCodeSpec(ecClassId))
@@ -815,6 +858,104 @@ class ChangedInstanceIds {
         else if (this.isElement(ecClassId))
             this.handleChange(this.element, changeType, change.ECInstanceId);
     }
+    /**
+     * Adds the provided change to the element changes maintained by this instance of ChangedInstanceIds
+     * If the same ECInstanceId is seen multiple times, the changedInstanceIds will be modified accordingly, i.e. if an id 'x' was updated but now we see 'x' was deleted, we will remove 'x'
+     * from the set of updatedIds and add it to the set of deletedIds for the appropriate class type.
+     * @note element changes will also cause the element's model to be marked as updated in [[ChangedInstanceIds.model]], so that the element does not get skipped by the transformer.
+     * @note It is the responsibility of the caller to ensure that the provided id is, in fact an element.
+     * @note In most cases, this method does not need to be called. Its only for consumers to mimic changes as if they were found in a changeset, which should only be useful in certain cases such as the changing of filter criteria for a preexisting master branch relationship.
+     */
+    addCustomElementChange(changeType, id // TODO: Support bulk adds
+    ) {
+        // if delete unnecessary?
+        this.addModelToUpdated(id);
+        this.handleChange(this.element, changeType, id);
+    }
+    /**
+     * Adds the provided change to the codespec changes maintained by this instance of ChangedInstanceIds
+     * If the same ECInstanceId is seen multiple times, the changedInstanceIds will be modified accordingly, i.e. if an id 'x' was updated but now we see 'x' was deleted, we will remove 'x'
+     * from the set of updatedIds and add it to the set of deletedIds for the appropriate class type.
+     * @note It is the responsibility of the caller to ensure that the provided id is, in fact a codespec.
+     * @note In most cases, this method does not need to be called. Its only for consumers to mimic changes as if they were found in a changeset, which should only be useful in certain cases such as the changing of filter criteria for a preexisting master branch relationship.
+     */
+    addCustomCodeSpecChange(changeType, id) {
+        this.handleChange(this.codeSpec, changeType, id);
+    }
+    /**
+     * Adds the provided change to the model changes maintained by this instance of ChangedInstanceIds
+     * If the same ECInstanceId is seen multiple times, the changedInstanceIds will be modified accordingly, i.e. if an id 'x' was updated but now we see 'x' was deleted, we will remove 'x'
+     * from the set of updatedIds and add it to the set of deletedIds for the appropriate class type.
+     * @note It is the responsibility of the caller to ensure that the provided id is, in fact a model.
+     * @note In most cases, this method does not need to be called. Its only for consumers to mimic changes as if they were found in a changeset, which should only be useful in certain cases such as the changing of filter criteria for a preexisting master branch relationship.
+     */
+    addCustomModelChange(changeType, id) {
+        this.handleChange(this.model, changeType, id);
+    }
+    /**
+     * Adds the provided change to the aspect changes maintained by this instance of ChangedInstanceIds
+     * If the same ECInstanceId is seen multiple times, the changedInstanceIds will be modified accordingly, i.e. if an id 'x' was updated but now we see 'x' was deleted, we will remove 'x'
+     * from the set of updatedIds and add it to the set of deletedIds for the appropriate class type.
+     * @note It is the responsibility of the caller to ensure that the provided id is, in fact an aspect.
+     * @note In most cases, this method does not need to be called. Its only for consumers to mimic changes as if they were found in a changeset, which should only be useful in certain cases such as the changing of filter criteria for a preexisting master branch relationship.
+     */
+    addCustomAspectChange(changeType, id) {
+        this.handleChange(this.aspect, changeType, id);
+    }
+    /**
+     * TODO: Think more about permutations of model updated / inserted / deleted. Can you delete a model without deleting its elements?
+     * What if model delete but custom change si to insert element into target?
+     *       // It is possible and apparently occasionally sensical to delete a model without deleting its underlying element.
+      // - If only the model is deleted, [[initFromExternalSourceAspects]] will have already remapped the underlying element since it still exists.
+      // - If both were deleted, [[remapDeletedSourceEntities]] will find and remap the deleted element making this operation valid
+     * TODO: If the element is a custom delete we probably shouldnt be calling this?
+     * There is an optimization in [IModelExporter.exportModelContents] which doesn't try to export elements within a model unless the model itself is part of
+     * the sourceDbChanges. This method is used in addCustomChange to add the model to the updatedIds set so that the custom element changes are exported.
+     */
+    addModelToUpdated(elementId) {
+        const modelId = this._db.elements.getElement(elementId).model;
+        this.handleChange(this.model, "Updated", modelId);
+    }
+    /** TODO: Maybe relationships only? maybe not. */
+    getCustomRelationshipDataFromId(id, type) {
+        if (type === "relationship") {
+            return this._entityReferenceToCustomDataMap.get(core_backend_1.EntityReferences.fromEntityType(id, core_common_1.ConcreteEntityTypes.Relationship));
+        }
+        return undefined;
+    }
+    /**
+     * Adds the provided change to the set of relationship changes maintained by this instance of ChangedInstanceIds.
+     * If the same ECInstanceId is seen multiple times, the changedInstanceIds will be modified accordingly, i.e. if an id 'x' was updated but now we see 'x' was deleted, we will remove 'x'
+     * from the set of updatedIds and add it to the set of deletedIds for the appropriate class type.
+     * @note In most cases, this method does not need to be called. Its only for consumers to mimic changes as if they were found in a changeset, which should only be useful in certain cases such as the changing of filter criteria for a preexisting master branch relationship.
+     * @throws if the ecClassId is NOT a relationship classId
+     * @param ecClassId class id of the custom change
+     * @param changeType insert, update or delete
+     * @param id ECInstanceID of the custom change
+     * @param sourceECInstanceId source ECInstanceId of the relationship
+     * @param targetECInstanceId target ECInstanceId of the relationship
+     */
+    async addCustomRelationshipChange(ecClassId, changeType, id, sourceECInstanceId, targetECInstanceId) {
+        if (!this._ecClassIdsInitialized)
+            await this.setupECClassIds();
+        if (this._relationshipSubclassIdsToSkip?.has(ecClassId))
+            return;
+        if (!this._relationshipSubclassIds?.has(ecClassId))
+            throw new Error(`Misuse. id: ${id}, ecClassId: ${ecClassId} is not a relationship class. Use 'addCustomChange' instead.`);
+        this._hasCustomChanges = true;
+        const classFullName = this._ecClassIdsToClassFullNames?.get(ecClassId);
+        (0, core_bentley_1.assert)(classFullName !== undefined); // setupECClassIds adds an entry to the above map for every single ECClassId.
+        this._entityReferenceToCustomDataMap.set(core_backend_1.EntityReferences.fromEntityType(id, core_common_1.ConcreteEntityTypes.Relationship), {
+            sourceIdOfRelationship: sourceECInstanceId,
+            targetIdOfRelationship: targetECInstanceId,
+            ecClassId,
+            classFullName,
+        });
+        this.handleChange(this.relationship, changeType, id);
+    }
+    getClassFullNameFromECClassId(ecClassid) {
+        return this._ecClassIdsToClassFullNames?.get(ecClassid);
+    }
     handleChange(changedInstanceOps, changeType, id) {
         // if changeType is a delete and we already have the id in the inserts then we can remove the id from the inserts.
         // if changeType is a delete and we already have the id in the updates then we can remove the id from the updates AND add it to the deletes.
@@ -839,12 +980,12 @@ class ChangedInstanceIds {
     }
     /**
      * Initializes a new ChangedInstanceIds object with information taken from a range of changesets.
+     * @public
      */
     static async initialize(opts) {
         if ("changedInstanceIds" in opts)
             return opts.changedInstanceIds;
         const iModelId = opts.iModel.iModelId;
-        const accessToken = opts.accessToken;
         const startChangeset = "startChangeset" in opts ? opts.startChangeset : undefined;
         const changesetRanges = startChangeset !== undefined
             ? [
@@ -855,13 +996,11 @@ class ChangedInstanceIds {
                             changeset: {
                                 id: startChangeset.id ?? opts.iModel.changeset.id,
                             },
-                            accessToken,
                         })).index,
                     opts.iModel.changeset.index ??
                         (await core_backend_1.IModelHost.hubAccess.queryChangeset({
                             iModelId,
                             changeset: { id: opts.iModel.changeset.id },
-                            accessToken,
                         })).index,
                 ],
             ]
@@ -870,7 +1009,6 @@ class ChangedInstanceIds {
                 : undefined;
         const csFileProps = changesetRanges !== undefined
             ? (await Promise.all(changesetRanges.map(async ([first, end]) => core_backend_1.IModelHost.hubAccess.downloadChangesets({
-                accessToken,
                 iModelId,
                 range: { first, end },
                 targetDir: core_backend_1.BriefcaseManager.getChangeSetsPath(iModelId),
@@ -881,10 +1019,6 @@ class ChangedInstanceIds {
         if (csFileProps === undefined)
             return undefined;
         const changedInstanceIds = new ChangedInstanceIds(opts.iModel);
-        const relationshipECClassIdsToSkip = new Set();
-        for await (const row of opts.iModel.createQueryReader("SELECT ECInstanceId FROM ECDbMeta.ECClassDef where ECInstanceId IS (BisCore.ElementDrivesElement)")) {
-            relationshipECClassIdsToSkip.add(row.ECInstanceId);
-        }
         for (const csFile of csFileProps) {
             const csReader = core_backend_1.SqliteChangesetReader.openFile({
                 fileName: csFile.pathname,
@@ -898,9 +1032,6 @@ class ChangedInstanceIds {
             }
             const changes = [...ecChangeUnifier.instances];
             for (const change of changes) {
-                if (change.ECClassId !== undefined &&
-                    relationshipECClassIdsToSkip.has(change.ECClassId))
-                    continue;
                 await changedInstanceIds.addChange(change);
             }
             csReader.close();