@itwin/imodel-transformer 2.0.0-dev.27 → 2.0.0-dev.28

package/lib/cjs/IModelTransformer.js

@@ -24,6 +24,7 @@ const EntityUnifier_1 = require("./EntityUnifier");
 const Algo_1 = require("./Algo");
 const SyncTypeResolver_1 = require("./SyncTypeResolver");
 const ProvenanceManager_1 = require("./ProvenanceManager");
+const IModelTransformerError_1 = require("./IModelTransformerError");
 const loggerCategory = TransformerLoggerCategory_1.TransformerLoggerCategory.IModelTransformer;
 /**
  * Apply a function to each Id64 in a supported container type of Id64s.
@@ -50,10 +51,16 @@ function mapId64(idContainer, func) {
         results.push(func(idContainer.id));
     }
     else {
-        throw Error([
-            `Id64 container '${JSON.stringify(idContainer)}' is unsupported.`,
-            "Currently only singular Id64 strings or prop-like objects containing an 'id' property are supported.",
-        ].join("\n"));
+        core_bentley_1.ITwinError.throwError({
+            iTwinErrorId: {
+                scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                key: IModelTransformerError_1.IModelTransformerError.InvalidEntityReference,
+            },
+            message: [
+                `Id64 container '${JSON.stringify(idContainer)}' is unsupported.`,
+                "Currently only singular Id64 strings or prop-like objects containing an 'id' property are supported.",
+            ].join("\n"),
+        });
     }
     return results;
 }
@@ -220,13 +227,23 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     validateSharedOptionsMatch() {
         if (Boolean(this._options.preserveElementIdsForFiltering) !==
             this.importer.options.preserveElementIdsForFiltering) {
-            const errMessage = "A custom importer was passed as a target but its 'preserveElementIdsForFiltering' option is out of sync with the transformer's option.";
-            throw new Error(errMessage);
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.ImporterOptionMismatch,
+                },
+                message: "A custom importer was passed as a target but its 'preserveElementIdsForFiltering' option is out of sync with the transformer's option.",
+            });
         }
         if (Boolean(this._options.skipPropagateChangesToRootElements) !==
             this.importer.options.skipPropagateChangesToRootElements) {
-            const errMessage = "A custom importer was passed as a target but its 'skipPropagateChangesToRootElements' option is out of sync with the transformer's option.";
-            throw new Error(errMessage);
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.ImporterOptionMismatch,
+                },
+                message: "A custom importer was passed as a target but its 'skipPropagateChangesToRootElements' option is out of sync with the transformer's option.",
+            });
         }
     }
     /** Dispose any native resources associated with this IModelTransformer. */
@@ -372,7 +389,13 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         const srcEcefLoc = this.sourceDb.ecefLocation;
         const targetEcefLoc = this.targetDb.ecefLocation;
         if (srcEcefLoc === undefined || targetEcefLoc === undefined) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NoGeoLocation, "Both source and target ECEF locations must be defined to calculate the transform.");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.GeolocationUnavailable,
+                },
+                message: "Both source and target ECEF locations must be defined to calculate the transform.",
+            });
         }
         if (srcEcefLoc.getTransform().isAlmostEqual(targetEcefLoc.getTransform())) {
             core_bentley_1.Logger.logTrace(loggerCategory, "ECEF data is already aligned. No spatial transforms needed.");
@@ -381,7 +404,13 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         const srcSpatialToECEF = srcEcefLoc.getTransform(); // converts relative to ECEF in relation to source
         const targetECEFToSpatial = targetEcefLoc.getTransform().inverse(); // converts ECEF to relative in relation to target
         if (!targetECEFToSpatial) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NoGeoLocation, "Failed to invert target ECEF transform.");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.GeolocationUnavailable,
+                },
+                message: "Failed to invert target ECEF transform.",
+            });
         }
         const ecefTransform = targetECEFToSpatial.multiplyTransformTransform(srcSpatialToECEF); // chain both transforms
         return ecefTransform;
@@ -399,15 +428,33 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     calculateTransformFromHelmertTransforms() {
         if (this.sourceDb.geographicCoordinateSystem?.horizontalCRS === undefined ||
             this.sourceDb.geographicCoordinateSystem?.verticalCRS === undefined) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Source iModel does not have a geographic coordinate system defined.");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.GeographicCoordinateSystemUnavailable,
+                },
+                message: "Source iModel does not have a geographic coordinate system defined.",
+            });
         }
         if (this.targetDb.geographicCoordinateSystem?.horizontalCRS === undefined ||
             this.targetDb.geographicCoordinateSystem.verticalCRS === undefined) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Target iModel does not have a geographic coordinate system defined.");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.GeographicCoordinateSystemUnavailable,
+                },
+                message: "Target iModel does not have a geographic coordinate system defined.",
+            });
         }
         if (!this.sourceDb.geographicCoordinateSystem.horizontalCRS.equals(this.targetDb.geographicCoordinateSystem.horizontalCRS) ||
             !this.sourceDb.geographicCoordinateSystem.verticalCRS.equals(this.targetDb.geographicCoordinateSystem.verticalCRS)) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.MismatchGcs, "Source and target geographic coordinate systems must match to calculate the spatial transform.");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.GeographicCoordinateSystemMismatch,
+                },
+                message: "Source and target geographic coordinate systems must match to calculate the spatial transform.",
+            });
         }
         if (this.sourceDb.geographicCoordinateSystem.additionalTransform ===
             this.targetDb.geographicCoordinateSystem.additionalTransform) {
@@ -419,14 +466,26 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         const targetScale = this.targetDb.geographicCoordinateSystem.additionalTransform
             ?.helmert2DWithZOffset?.scale ?? 1;
         if (srcScale !== targetScale) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.MismatchGcs, "Spatial transform is non rigid. Source and target Helmert transforms must have the same scale to calculate a rigid spatial transform.");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.GeographicCoordinateSystemMismatch,
+                },
+                message: "Spatial transform is non rigid. Source and target Helmert transforms must have the same scale to calculate a rigid spatial transform.",
+            });
         }
         const srcTransform = IModelTransformer.convertHelmertToTransform(this.sourceDb.geographicCoordinateSystem.additionalTransform
             ?.helmert2DWithZOffset); // moves elements to where src helmert transform would move them at render time
         const targetTransformInv = IModelTransformer.convertHelmertToTransform(this.targetDb.geographicCoordinateSystem.additionalTransform
             ?.helmert2DWithZOffset).inverse(); // negates target helmert transform that is applied at render time
         if (!targetTransformInv) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NoGeoLocation, "Failed to invert target Helmert transform.");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.GeolocationUnavailable,
+                },
+                message: "Failed to invert target Helmert transform.",
+            });
         }
         const combinedTransform = targetTransformInv.multiplyTransformTransform(srcTransform);
         return combinedTransform;
@@ -503,12 +562,18 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             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"));
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.DanglingReference,
+                },
+                message: [
+                    `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.
@@ -518,7 +583,13 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     async processElement(sourceElementId) {
         await this.initialize();
         if (sourceElementId === core_common_1.IModel.rootSubjectId) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "The root Subject should not be directly imported");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.RootSubjectNotProcessable,
+                },
+                message: "The root Subject should not be directly imported",
+            });
         }
         return this.exporter.exportElement(sourceElementId);
     }
@@ -607,9 +678,21 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     // It mimicks 4.x implementation: https://github.com/iTwin/itwinjs-core/blob/9c8b394ec3878a39764be81f928fd8b0b9115d31/core/backend/src/IModelDb.ts#L1882
     async queryElementIdByCode(iModel, code) {
         if (core_bentley_1.Id64.isInvalid(code.spec))
-            throw new Error("Invalid CodeSpec");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.InvalidCode,
+                },
+                message: "Invalid CodeSpec",
+            });
         if (code.value === undefined)
-            throw new Error("Invalid Code");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.InvalidCode,
+                },
+                message: "Invalid Code",
+            });
         const query = "SELECT ECInstanceId FROM BisCore:Element WHERE CodeSpec.Id=? AND CodeScope.Id=? AND CodeValue=?";
         const queryBinder = new core_common_1.QueryBinder()
             .bindId(1, code.spec)
@@ -679,7 +762,13 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             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`);
+                core_bentley_1.ITwinError.throwError({
+                    iTwinErrorId: {
+                        scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                        key: IModelTransformerError_1.IModelTransformerError.ElementIdNotPreservable,
+                    },
+                    message: `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)
@@ -690,7 +779,13 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 // 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}`);
+                    core_bentley_1.ITwinError.throwError({
+                        iTwinErrorId: {
+                            scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                            key: IModelTransformerError_1.IModelTransformerError.ElementIdNotPreservable,
+                        },
+                        message: `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
@@ -702,7 +797,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             await this.importer.importElement(targetElementProps); // don't need to import if iModel was copied
         }
         if (targetElementProps.id === undefined) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadElement, "targetElementProps.id should be assigned by importElement");
+            throw new Error("targetElementProps.id should be assigned by importElement");
         }
         this.context.remapElement(sourceElement.id, targetElementProps.id);
         // the transformer does not currently 'split' or 'join' any elements, therefore, it does not
@@ -761,7 +856,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         const targetModelProps = this.onTransformModel(sourceModel, targetModeledElementId);
         await this.importer.importModel(targetModelProps);
         if (targetModelProps.id === undefined) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadModel, "targetModelProps.id should be assigned by now");
+            throw new Error("targetModelProps.id should be assigned by now");
         }
         this._targetModelsImportedInCurrentTransform.add(targetModelProps.id);
     }
@@ -884,7 +979,13 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
         };
         targetModelProps.id = targetModeledElementId;
         if (targetModelProps.parentModel === undefined) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadElement, "targetElementProps must have a defined parentModel");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.ParentModelRequired,
+                },
+                message: "targetElementProps must have a defined parentModel",
+            });
         }
         targetModelProps.parentModel = this.context.findTargetElementId(targetModelProps.parentModel);
         return targetModelProps;
@@ -1283,9 +1384,21 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
                 const changeType = change.$meta?.op;
                 const ecClassId = change.ECClassId ?? change.$meta?.fallbackClassId;
                 if (ecClassId === undefined)
-                    throw new Error(`ECClassId was not found for id: ${change.ECInstanceId}! Table is : ${change?.$meta?.tables}`);
+                    core_bentley_1.ITwinError.throwError({
+                        iTwinErrorId: {
+                            scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                            key: IModelTransformerError_1.IModelTransformerError.ChangedInstanceMetadataMissing,
+                        },
+                        message: `ECClassId was not found for id: ${change.ECInstanceId}! Table is : ${change?.$meta?.tables}`,
+                    });
                 if (changeType === undefined)
-                    throw new Error(`ChangeType was undefined for id: ${change.ECInstanceId}.`);
+                    core_bentley_1.ITwinError.throwError({
+                        iTwinErrorId: {
+                            scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                            key: IModelTransformerError_1.IModelTransformerError.ChangedInstanceMetadataMissing,
+                        },
+                        message: `ChangeType was undefined for id: ${change.ECInstanceId}.`,
+                    });
                 if (changeType !== "Deleted" ||
                     relationshipECClassIdsToSkip.has(ecClassId))
                     continue;
@@ -1408,7 +1521,7 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             if (deletionNotInTarget)
                 return;
             if (targetId === undefined) {
-                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadElement, "targetId should be acquired from source id or element provenance");
+                throw new Error("targetId should be acquired from source id or element provenance");
             }
             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.
@@ -1451,13 +1564,19 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
             ?.ignoreMissingChangesetsInSynchronizations &&
             startChangesetIndex !== syncVersion.index + 1 &&
             syncVersion.index !== -1) {
-            throw Error(`synchronization is ${missingChangesets ? "missing changesets" : ""},` +
-                " startChangesetId should be" +
-                " exactly the first changeset *after* the previous synchronization to not miss data." +
-                ` You specified '${startChangesetIndexOrId}' which is changeset #${startChangesetIndex}` +
-                ` but the previous synchronization for this targetScopeElem ${syncVersion.id}'` +
-                ` which is changeset #${syncVersion.index}. The transformer expected` +
-                ` #${syncVersion.index + 1}.`);
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.SynchronizationRangeInvalid,
+                },
+                message: `synchronization is ${missingChangesets ? "missing changesets" : ""},` +
+                    " startChangesetId should be" +
+                    " exactly the first changeset *after* the previous synchronization to not miss data." +
+                    ` You specified '${startChangesetIndexOrId}' which is changeset #${startChangesetIndex}` +
+                    ` but the previous synchronization for this targetScopeElem ${syncVersion.id}'` +
+                    ` which is changeset #${syncVersion.index}. The transformer expected` +
+                    ` #${syncVersion.index + 1}.`,
+            });
         }
         const changesetsToSkip = await this._provenanceManager.getChangesetsToSkip();
         core_bentley_1.Logger.logTrace(loggerCategory, `changesets to skip: ${changesetsToSkip}`);
@@ -1481,10 +1600,22 @@ class IModelTransformer extends IModelExporter_1.IModelExportHandler {
     /** Asserts that the EditTxn is active before any write operations. */
     assertEditTxnActive() {
         if (!this._targetEditTxn.isActive) {
-            throw new Error("The target EditTxn must be started before calling process(). Call targetEditTxn.start() before invoking the transformer.");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.EditTxnNotActive,
+                },
+                message: "The target EditTxn must be started before calling process(). Call targetEditTxn.start() before invoking the transformer.",
+            });
         }
         if (this._sourceEditTxn && !this._sourceEditTxn.isActive) {
-            throw new Error("The source EditTxn was provided but is not active. Call sourceEditTxn.start() before invoking the transformer.");
+            core_bentley_1.ITwinError.throwError({
+                iTwinErrorId: {
+                    scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                    key: IModelTransformerError_1.IModelTransformerError.EditTxnNotActive,
+                },
+                message: "The source EditTxn was provided but is not active. Call sourceEditTxn.start() before invoking the transformer.",
+            });
         }
     }
     /**
@@ -1676,7 +1807,13 @@ class TemplateModelCloner extends IModelTransformer {
             // TODO: consider going through all definition elements at once and remapping them to themselves
             if (!core_backend_1.EntityReferences.isValid(await this.context.findTargetEntityId(referenceId))) {
                 if (this.context.isBetweenIModels) {
-                    throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, `Remapping for source dependency ${referenceId} not found for target iModel`);
+                    core_bentley_1.ITwinError.throwError({
+                        iTwinErrorId: {
+                            scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                            key: IModelTransformerError_1.IModelTransformerError.DependencyMappingMissing,
+                        },
+                        message: `Remapping for source dependency ${referenceId} not found for target iModel`,
+                    });
                 }
                 else {
                     const definitionElement = this.sourceDb.elements.tryGetElement(referenceId, core_backend_1.DefinitionElement);
@@ -1685,7 +1822,13 @@ class TemplateModelCloner extends IModelTransformer {
                         this.context.remapElement(referenceId, referenceId); // when in the same iModel, can use existing DefinitionElements without remapping
                     }
                     else {
-                        throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, `Remapping for dependency ${referenceId} not found`);
+                        core_bentley_1.ITwinError.throwError({
+                            iTwinErrorId: {
+                                scope: IModelTransformerError_1.IModelTransformerErrorScope,
+                                key: IModelTransformerError_1.IModelTransformerError.DependencyMappingMissing,
+                            },
+                            message: `Remapping for dependency ${referenceId} not found`,
+                        });
                     }
                 }
             }