@itwin/imodel-transformer 0.0.1-dev.0

package/lib/cjs/IModelTransformer.js

@@ -0,0 +1,1357 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TemplateModelCloner = exports.IModelTransformer = void 0;
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module iModels
+ */
+const path = require("path");
+const Semver = require("semver");
+const nodeAssert = require("assert");
+const core_bentley_1 = require("@itwin/core-bentley");
+const core_geometry_1 = require("@itwin/core-geometry");
+const core_backend_1 = require("@itwin/core-backend");
+const core_common_1 = require("@itwin/core-common");
+const IModelExporter_1 = require("./IModelExporter");
+const IModelImporter_1 = require("./IModelImporter");
+const TransformerLoggerCategory_1 = require("./TransformerLoggerCategory");
+const PendingReferenceMap_1 = require("./PendingReferenceMap");
+const EntityMap_1 = require("./EntityMap");
+const IModelCloneContext_1 = require("./IModelCloneContext");
+const EntityUnifier_1 = require("./EntityUnifier");
+const loggerCategory = TransformerLoggerCategory_1.TransformerLoggerCategory.IModelTransformer;
+const nullLastProvenanceEntityInfo = {
+    entityId: core_bentley_1.Id64.invalid,
+    aspectId: core_bentley_1.Id64.invalid,
+    aspectVersion: "",
+    aspectKind: core_backend_1.ExternalSourceAspect.Kind.Element,
+};
+/**
+ * A container for tracking the state of a partially committed entity and finalizing it when it's ready to be fully committed
+ * @internal
+ */
+class PartiallyCommittedEntity {
+    constructor(
+    /**
+     * A set of "model|element ++ ID64" pairs, (e.g. `model0x11` or `element0x12`)
+     * It is possible for the submodel of an element to be separately resolved from the actual element,
+     * so its resolution must be tracked separately
+     */
+    _missingReferences, _onComplete) {
+        this._missingReferences = _missingReferences;
+        this._onComplete = _onComplete;
+    }
+    resolveReference(id) {
+        this._missingReferences.delete(id);
+        if (this._missingReferences.size === 0)
+            this._onComplete();
+    }
+    forceComplete() {
+        this._onComplete();
+    }
+}
+/**
+ * Apply a function to each Id64 in a supported container type of Id64s.
+ * Currently only supports raw Id64String or RelatedElement-like objects containing an `id` property that is a Id64String,
+ * which matches the possible containers of references in [Element.requiredReferenceKeys]($backend).
+ * @internal
+ */
+function mapId64(idContainer, func) {
+    const isId64String = (arg) => {
+        const isString = typeof arg === "string";
+        (0, core_bentley_1.assert)(() => !isString || core_bentley_1.Id64.isValidId64(arg));
+        return isString;
+    };
+    const isRelatedElem = (arg) => arg && typeof arg === "object" && "id" in arg;
+    const results = [];
+    // is a string if compressed or singular id64, but check for singular just checks if it's a string so do this test first
+    if (idContainer === undefined) {
+        // nothing
+    }
+    else if (isId64String(idContainer)) {
+        results.push(func(idContainer));
+    }
+    else if (isRelatedElem(idContainer)) {
+        results.push(func(idContainer.id));
+    }
+    else {
+        throw Error([
+            `Id64 container '${idContainer}' is unsupported.`,
+            "Currently only singular Id64 strings or prop-like objects containing an 'id' property are supported.",
+        ].join("\n"));
+    }
+    return results;
+}
+/** 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
+ */
+class IModelTransformer extends IModelExporter_1.IModelExportHandler {
+    /** 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.
+     * @param options The options that specify how the transformation should be done.
+     */
+    constructor(source, target, options) {
+        var _a, _b, _c, _d, _e;
+        super();
+        /** map of (unprocessed element, referencing processed element) pairs to the partially committed element that needs the reference resolved
+         * and have some helper methods below for now */
+        this._pendingReferences = new PendingReferenceMap_1.PendingReferenceMap();
+        /** map of partially committed entities to their partial commit progress */
+        this._partiallyCommittedEntities = new EntityMap_1.EntityMap();
+        this._yieldManager = new core_bentley_1.YieldManager();
+        /** The directory where schemas will be exported, a random temporary directory */
+        this._schemaExportDir = path.join(core_backend_1.KnownLocations.tmpdir, core_bentley_1.Guid.createValue());
+        this._longNamedSchemasMap = new Map();
+        /** state to prevent reinitialization, @see [[initialize]] */
+        this._initialized = false;
+        this._lastProvenanceEntityInfo = nullLastProvenanceEntityInfo;
+        // initialize IModelTransformOptions
+        this._options = {
+            ...options,
+            // non-falsy defaults
+            cloneUsingBinaryGeometry: (_a = options === null || options === void 0 ? void 0 : options.cloneUsingBinaryGeometry) !== null && _a !== void 0 ? _a : true,
+            targetScopeElementId: (_b = options === null || options === void 0 ? void 0 : options.targetScopeElementId) !== null && _b !== void 0 ? _b : core_common_1.IModel.rootSubjectId,
+            // eslint-disable-next-line deprecation/deprecation
+            danglingReferencesBehavior: (_d = (_c = options === null || options === void 0 ? void 0 : options.danglingReferencesBehavior) !== null && _c !== void 0 ? _c : options === null || options === void 0 ? void 0 : options.danglingPredecessorsBehavior) !== null && _d !== void 0 ? _d : "reject",
+        };
+        this._isFirstSynchronization = this._options.wasSourceIModelCopiedToTarget ? true : undefined;
+        // initialize exporter and sourceDb
+        if (source instanceof core_backend_1.IModelDb) {
+            this.exporter = new IModelExporter_1.IModelExporter(source);
+        }
+        else {
+            this.exporter = source;
+        }
+        this.sourceDb = this.exporter.sourceDb;
+        this.exporter.registerHandler(this);
+        this.exporter.wantGeometry = (_e = options === null || options === void 0 ? void 0 : options.loadSourceGeometry) !== null && _e !== void 0 ? _e : false; // optimization to not load source GeometryStreams by default
+        if (!this._options.includeSourceProvenance) { // clone provenance from the source iModel into the target iModel?
+            IModelTransformer.provenanceElementClasses.forEach((cls) => this.exporter.excludeElementClass(cls.classFullName));
+            IModelTransformer.provenanceElementAspectClasses.forEach((cls) => this.exporter.excludeElementAspectClass(cls.classFullName));
+        }
+        this.exporter.excludeElementAspectClass(core_backend_1.ChannelRootAspect.classFullName); // Channel boundaries within the source iModel are not relevant to the target iModel
+        this.exporter.excludeElementAspectClass("BisCore:TextAnnotationData"); // This ElementAspect is auto-created by the BisCore:TextAnnotation2d/3d element handlers
+        // initialize importer and targetDb
+        if (target instanceof core_backend_1.IModelDb) {
+            this.importer = new IModelImporter_1.IModelImporter(target, { preserveElementIdsForFiltering: this._options.preserveElementIdsForFiltering });
+        }
+        else {
+            this.importer = target;
+            /* eslint-disable deprecation/deprecation */
+            if (Boolean(this._options.preserveElementIdsForFiltering) !== this.importer.preserveElementIdsForFiltering) {
+                core_bentley_1.Logger.logWarning(loggerCategory, [
+                    "A custom importer was passed as a target but its 'preserveElementIdsForFiltering' option is out of sync with the transformer's option.",
+                    "The custom importer target's option will be force updated to use the transformer's value.",
+                    "This behavior is deprecated and will be removed in a future version, throwing an error if they are out of sync.",
+                ].join("\n"));
+                this.importer.preserveElementIdsForFiltering = Boolean(this._options.preserveElementIdsForFiltering);
+            }
+            /* eslint-enable deprecation/deprecation */
+        }
+        this.targetDb = this.importer.targetDb;
+        // create the IModelCloneContext, it must be initialized later
+        this.context = new IModelCloneContext_1.IModelCloneContext(this.sourceDb, this.targetDb);
+    }
+    /** 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() {
+        return this._options.targetScopeElementId;
+    }
+    /** The element classes that are considered to define provenance in the iModel */
+    static get provenanceElementClasses() {
+        return [core_backend_1.FolderLink, core_backend_1.SynchronizationConfigLink, core_backend_1.ExternalSource, core_backend_1.ExternalSourceAttachment];
+    }
+    /** The element aspect classes that are considered to define provenance in the iModel */
+    static get provenanceElementAspectClasses() {
+        return [core_backend_1.ExternalSourceAspect];
+    }
+    /** Dispose any native resources associated with this IModelTransformer. */
+    dispose() {
+        core_bentley_1.Logger.logTrace(loggerCategory, "dispose()");
+        this.context.dispose();
+    }
+    /** Log current settings that affect IModelTransformer's behavior. */
+    logSettings() {
+        core_bentley_1.Logger.logInfo(TransformerLoggerCategory_1.TransformerLoggerCategory.IModelExporter, `this.exporter.visitElements=${this.exporter.visitElements}`);
+        core_bentley_1.Logger.logInfo(TransformerLoggerCategory_1.TransformerLoggerCategory.IModelExporter, `this.exporter.visitRelationships=${this.exporter.visitRelationships}`);
+        core_bentley_1.Logger.logInfo(TransformerLoggerCategory_1.TransformerLoggerCategory.IModelExporter, `this.exporter.wantGeometry=${this.exporter.wantGeometry}`);
+        core_bentley_1.Logger.logInfo(TransformerLoggerCategory_1.TransformerLoggerCategory.IModelExporter, `this.exporter.wantSystemSchemas=${this.exporter.wantSystemSchemas}`);
+        core_bentley_1.Logger.logInfo(TransformerLoggerCategory_1.TransformerLoggerCategory.IModelExporter, `this.exporter.wantTemplateModels=${this.exporter.wantTemplateModels}`);
+        core_bentley_1.Logger.logInfo(loggerCategory, `this.targetScopeElementId=${this.targetScopeElementId}`);
+        core_bentley_1.Logger.logInfo(loggerCategory, `this._noProvenance=${this._options.noProvenance}`);
+        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, `this._isReverseSynchronization=${this._options.isReverseSynchronization}`);
+        core_bentley_1.Logger.logInfo(TransformerLoggerCategory_1.TransformerLoggerCategory.IModelImporter, `this.importer.autoExtendProjectExtents=${this.importer.options.autoExtendProjectExtents}`);
+        core_bentley_1.Logger.logInfo(TransformerLoggerCategory_1.TransformerLoggerCategory.IModelImporter, `this.importer.simplifyElementGeometry=${this.importer.options.simplifyElementGeometry}`);
+    }
+    /** Return the IModelDb where IModelTransformer will store its provenance.
+     * @note This will be [[targetDb]] except when it is a reverse synchronization. In that case it be [[sourceDb]].
+     */
+    get provenanceDb() {
+        return this._options.isReverseSynchronization ? this.sourceDb : this.targetDb;
+    }
+    /** Create an ExternalSourceAspectProps in a standard way for an Element in an iModel --> iModel transformation. */
+    initElementProvenance(sourceElementId, targetElementId) {
+        const elementId = this._options.isReverseSynchronization ? sourceElementId : targetElementId;
+        const aspectIdentifier = this._options.isReverseSynchronization ? targetElementId : sourceElementId;
+        const aspectProps = {
+            classFullName: core_backend_1.ExternalSourceAspect.classFullName,
+            element: { id: elementId, relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName },
+            scope: { id: this.targetScopeElementId },
+            identifier: aspectIdentifier,
+            kind: core_backend_1.ExternalSourceAspect.Kind.Element,
+            version: this.sourceDb.elements.queryLastModifiedTime(sourceElementId),
+        };
+        return aspectProps;
+    }
+    /** Create an ExternalSourceAspectProps in a standard way for a Relationship in an iModel --> iModel transformations.
+     * The ExternalSourceAspect is meant to be owned by the Element in the target iModel that is the `sourceId` of transformed relationship.
+     * The `identifier` property of the ExternalSourceAspect will be the ECInstanceId of the relationship in the source iModel.
+     * The ECInstanceId of the relationship in the target iModel will be stored in the JsonProperties of the ExternalSourceAspect.
+     */
+    initRelationshipProvenance(sourceRelationship, targetRelInstanceId) {
+        const targetRelationship = this.targetDb.relationships.getInstance(core_backend_1.ElementRefersToElements.classFullName, targetRelInstanceId);
+        const elementId = this._options.isReverseSynchronization ? sourceRelationship.sourceId : targetRelationship.sourceId;
+        const aspectIdentifier = this._options.isReverseSynchronization ? targetRelInstanceId : sourceRelationship.id;
+        const aspectProps = {
+            classFullName: core_backend_1.ExternalSourceAspect.classFullName,
+            element: { id: elementId, relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName },
+            scope: { id: this.targetScopeElementId },
+            identifier: aspectIdentifier,
+            kind: core_backend_1.ExternalSourceAspect.Kind.Relationship,
+            jsonProperties: JSON.stringify({ targetRelInstanceId }),
+        };
+        aspectProps.id = this.queryExternalSourceAspectId(aspectProps);
+        return aspectProps;
+    }
+    validateScopeProvenance() {
+        const aspectProps = {
+            classFullName: core_backend_1.ExternalSourceAspect.classFullName,
+            element: { id: this.targetScopeElementId, relClassName: core_backend_1.ElementOwnsExternalSourceAspects.classFullName },
+            scope: { id: core_common_1.IModel.rootSubjectId },
+            identifier: this._options.isReverseSynchronization ? this.targetDb.iModelId : this.sourceDb.iModelId,
+            kind: core_backend_1.ExternalSourceAspect.Kind.Scope,
+        };
+        aspectProps.id = this.queryExternalSourceAspectId(aspectProps); // this query includes "identifier"
+        if (undefined === aspectProps.id) {
+            // this query does not include "identifier" to find possible conflicts
+            const sql = `SELECT ECInstanceId FROM ${core_backend_1.ExternalSourceAspect.classFullName} WHERE Element.Id=:elementId AND Scope.Id=:scopeId AND Kind=:kind LIMIT 1`;
+            const hasConflictingScope = this.provenanceDb.withPreparedStatement(sql, (statement) => {
+                statement.bindId("elementId", aspectProps.element.id);
+                statement.bindId("scopeId", aspectProps.scope.id); // this scope.id can never be invalid, we create it above
+                statement.bindString("kind", aspectProps.kind);
+                return core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step();
+            });
+            if (hasConflictingScope) {
+                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.InvalidId, "Provenance scope conflict");
+            }
+            if (!this._options.noProvenance) {
+                this.provenanceDb.elements.insertAspect(aspectProps);
+                this._isFirstSynchronization = true; // couldn't tell this is the first time without provenance
+            }
+        }
+    }
+    queryExternalSourceAspectId(aspectProps) {
+        const sql = `SELECT ECInstanceId FROM ${core_backend_1.ExternalSourceAspect.classFullName} WHERE Element.Id=:elementId AND Scope.Id=:scopeId AND Kind=:kind AND Identifier=:identifier LIMIT 1`;
+        return this.provenanceDb.withPreparedStatement(sql, (statement) => {
+            statement.bindId("elementId", aspectProps.element.id);
+            if (aspectProps.scope === undefined)
+                return undefined; // return undefined instead of binding an invalid id
+            statement.bindId("scopeId", aspectProps.scope.id);
+            statement.bindString("kind", aspectProps.kind);
+            statement.bindString("identifier", aspectProps.identifier);
+            return (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) ? statement.getValue(0).getId() : undefined;
+        });
+    }
+    /** Iterate all matching ExternalSourceAspects in the provenance iModel (target unless reverse sync) and call a function for each one. */
+    forEachTrackedElement(fn) {
+        if (!this.provenanceDb.containsClass(core_backend_1.ExternalSourceAspect.classFullName)) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadSchema, "The BisCore schema version of the target database is too old");
+        }
+        const sql = `SELECT Identifier,Element.Id FROM ${core_backend_1.ExternalSourceAspect.classFullName} WHERE Scope.Id=:scopeId AND Kind=:kind`;
+        this.provenanceDb.withPreparedStatement(sql, (statement) => {
+            statement.bindId("scopeId", this.targetScopeElementId);
+            statement.bindString("kind", core_backend_1.ExternalSourceAspect.Kind.Element);
+            while (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) {
+                const aspectIdentifier = statement.getValue(0).getString(); // ExternalSourceAspect.Identifier is of type string
+                const elementId = statement.getValue(1).getId();
+                if (this._options.isReverseSynchronization) {
+                    fn(elementId, aspectIdentifier); // provenance coming from the sourceDb
+                }
+                else {
+                    fn(aspectIdentifier, elementId); // provenance coming from the targetDb
+                }
+            }
+        });
+    }
+    /** Initialize the source to target Element mapping from ExternalSourceAspects in the target iModel.
+     * @note This method is called from all `process*` functions and should never need to be called directly.
+     * @deprecated in 3.x. call [[initialize]] instead, it does the same thing among other initialization
+     * @note Passing an [[InitFromExternalSourceAspectsArgs]] is required when processing changes, to remap any elements that may have been deleted.
+     *       You must await the returned promise as well in this case. The synchronous behavior has not changed but is deprecated and won't process everything.
+     */
+    initFromExternalSourceAspects(args) {
+        this.forEachTrackedElement((sourceElementId, targetElementId) => {
+            this.context.remapElement(sourceElementId, targetElementId);
+        });
+        if (args)
+            return this.remapDeletedSourceElements(args);
+    }
+    /** When processing deleted elements in a reverse synchronization, the [[provenanceDb]] (usually a branch iModel) has already
+     * deleted the [ExternalSourceAspect]($backend)s that tell us which elements in the reverse synchronization target (usually
+     * a master iModel) should be deleted. We must use the changesets to get the values of those before they were deleted.
+     */
+    async remapDeletedSourceElements(args) {
+        var _a;
+        // we need a connected iModel with changes to remap elements with deletions
+        if (this.sourceDb.iTwinId === undefined)
+            return;
+        try {
+            const startChangesetId = (_a = args.startChangesetId) !== null && _a !== void 0 ? _a : this.sourceDb.changeset.id;
+            const endChangesetId = this.sourceDb.changeset.id;
+            const [firstChangesetIndex, endChangesetIndex] = await Promise.all([startChangesetId, endChangesetId]
+                .map(async (id) => core_backend_1.IModelHost.hubAccess
+                .queryChangeset({
+                iModelId: this.sourceDb.iModelId,
+                changeset: { id },
+                accessToken: args.accessToken,
+            })
+                .then((changeset) => changeset.index)));
+            const changesetIds = await core_backend_1.ChangeSummaryManager.createChangeSummaries({
+                accessToken: args.accessToken,
+                iModelId: this.sourceDb.iModelId,
+                iTwinId: this.sourceDb.iTwinId,
+                range: { first: firstChangesetIndex, end: endChangesetIndex },
+            });
+            core_backend_1.ChangeSummaryManager.attachChangeCache(this.sourceDb);
+            for (const changesetId of changesetIds) {
+                this.sourceDb.withPreparedStatement(`
+          SELECT esac.Element.Id, esac.Identifier
+          FROM ecchange.change.InstanceChange ic
+          JOIN BisCore.ExternalSourceAspect.Changes(:changesetId, 'BeforeDelete') esac
+            ON ic.ChangedInstance.Id=esac.ECInstanceId
+          WHERE ic.OpCode=:opcode
+            AND ic.Summary.Id=:changesetId
+            AND esac.Scope.Id=:targetScopeElementId
+            -- not yet documented ecsql feature to check class id
+            AND ic.ChangedInstance.ClassId IS (ONLY BisCore.ExternalSourceAspect)
+          `, (stmt) => {
+                    stmt.bindInteger("opcode", core_common_1.ChangeOpCode.Delete);
+                    stmt.bindInteger("changesetId", changesetId);
+                    stmt.bindInteger("targetScopeElementId", this.targetScopeElementId);
+                    while (core_bentley_1.DbResult.BE_SQLITE_ROW === stmt.step()) {
+                        const targetId = stmt.getValue(0).getId();
+                        const sourceId = stmt.getValue(1).getString(); // BisCore.ExternalSourceAspect.Identifier stores a hex Id64String
+                        // TODO: maybe delete and don't just remap
+                        this.context.remapElement(targetId, sourceId);
+                    }
+                });
+            }
+        }
+        finally {
+            if (core_backend_1.ChangeSummaryManager.isChangeCacheAttached(this.sourceDb))
+                core_backend_1.ChangeSummaryManager.detachChangeCache(this.sourceDb);
+        }
+    }
+    /** Returns `true` if *brute force* delete detections should be run.
+     * @note Not relevant for processChanges when change history is known.
+     */
+    shouldDetectDeletes() {
+        if (this._isFirstSynchronization)
+            return false; // not necessary the first time since there are no deletes to detect
+        if (this._options.isReverseSynchronization)
+            return false; // not possible for a reverse synchronization since provenance will be deleted when element is deleted
+        return true;
+    }
+    /** Detect Element deletes using ExternalSourceAspects in the target iModel and a *brute force* comparison against Elements in the source iModel.
+     * @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.
+     * @throws [[IModelError]] If the required provenance information is not available to detect deletes.
+     */
+    async detectElementDeletes() {
+        if (this._options.isReverseSynchronization) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Cannot detect deletes when isReverseSynchronization=true");
+        }
+        const targetElementsToDelete = [];
+        this.forEachTrackedElement((sourceElementId, targetElementId) => {
+            if (undefined === this.sourceDb.elements.tryGetElementProps(sourceElementId)) {
+                // if the sourceElement is not found, then it must have been deleted, so propagate the delete to the target iModel
+                targetElementsToDelete.push(targetElementId);
+            }
+        });
+        targetElementsToDelete.forEach((targetElementId) => {
+            this.importer.deleteElement(targetElementId);
+        });
+    }
+    /**
+     * @deprecated in 3.x, this no longer has any effect except emitting a warning
+     */
+    skipElement(_sourceElement) {
+        core_bentley_1.Logger.logWarning(loggerCategory, `Tried to defer/skip an element, which is no longer necessary`);
+    }
+    /** Transform the specified sourceElement into ElementProps for the target iModel.
+     * @param sourceElement The Element from the source iModel to transform.
+     * @returns ElementProps for the target iModel.
+     * @note A subclass can override this method to provide custom transform behavior.
+     * @note This can be called more than once for an element in arbitrary order, so it should not have side-effects.
+     */
+    onTransformElement(sourceElement) {
+        var _a, _b;
+        core_bentley_1.Logger.logTrace(loggerCategory, `onTransformElement(${sourceElement.id}) "${sourceElement.getDisplayLabel()}"`);
+        const targetElementProps = this.context.cloneElement(sourceElement, { binaryGeometry: this._options.cloneUsingBinaryGeometry });
+        if (sourceElement instanceof core_backend_1.Subject) {
+            if ((_b = (_a = targetElementProps.jsonProperties) === null || _a === void 0 ? void 0 : _a.Subject) === null || _b === void 0 ? void 0 : _b.Job) {
+                // don't propagate source channels into target (legacy bridge case)
+                targetElementProps.jsonProperties.Subject.Job = undefined;
+            }
+        }
+        return targetElementProps;
+    }
+    /** 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.
+     */
+    hasElementChanged(sourceElement, targetElementId) {
+        const sourceAspects = this.targetDb.elements.getAspects(targetElementId, core_backend_1.ExternalSourceAspect.classFullName);
+        for (const sourceAspect of sourceAspects) {
+            if (sourceAspect.scope === undefined) // if the scope was lost, we can't correlate so assume it changed
+                return true;
+            if (sourceAspect.identifier === sourceElement.id &&
+                sourceAspect.scope.id === this.targetScopeElementId &&
+                sourceAspect.kind === core_backend_1.ExternalSourceAspect.Kind.Element) {
+                const lastModifiedTime = sourceElement.iModel.elements.queryLastModifiedTime(sourceElement.id);
+                return lastModifiedTime !== sourceAspect.version;
+            }
+        }
+        return true;
+    }
+    static transformCallbackFor(transformer, entity) {
+        if (entity instanceof core_backend_1.Element)
+            return transformer.onTransformElement; // eslint-disable-line @typescript-eslint/unbound-method
+        else if (entity instanceof core_backend_1.Element)
+            return transformer.onTransformModel; // eslint-disable-line @typescript-eslint/unbound-method
+        else if (entity instanceof core_backend_1.Relationship)
+            return transformer.onTransformRelationship; // eslint-disable-line @typescript-eslint/unbound-method
+        else if (entity instanceof core_backend_1.ElementAspect)
+            return transformer.onTransformElementAspect; // eslint-disable-line @typescript-eslint/unbound-method
+        else
+            (0, core_bentley_1.assert)(false, `unreachable; entity was '${entity.constructor.name}' not an Element, Relationship, or ElementAspect`);
+    }
+    /** callback to perform when a partial element says it's ready to be completed
+     * transforms the source element with all references now valid, then updates the partial element with the results
+     */
+    makePartialEntityCompleter(sourceEntity) {
+        return () => {
+            const targetId = this.context.findTargetEntityId(core_backend_1.EntityReferences.from(sourceEntity));
+            if (!core_backend_1.EntityReferences.isValid(targetId))
+                throw Error(`${sourceEntity.id} has not been inserted into the target yet, the completer is invalid. This is a bug.`);
+            const onEntityTransform = IModelTransformer.transformCallbackFor(this, sourceEntity);
+            const updateEntity = EntityUnifier_1.EntityUnifier.updaterFor(this.targetDb, sourceEntity);
+            const targetProps = onEntityTransform.call(this, sourceEntity);
+            if (sourceEntity instanceof core_backend_1.Relationship) {
+                targetProps.sourceId = this.context.findTargetElementId(sourceEntity.sourceId);
+                targetProps.targetId = this.context.findTargetElementId(sourceEntity.targetId);
+            }
+            updateEntity({ ...targetProps, id: core_backend_1.EntityReferences.toId64(targetId) });
+            this._partiallyCommittedEntities.delete(sourceEntity);
+        };
+    }
+    /** collect references this entity has that are yet to be mapped, and if there are any
+     * create a [[PartiallyCommittedEntity]] to track resolution of those references
+     */
+    collectUnmappedReferences(entity) {
+        const missingReferences = new core_common_1.EntityReferenceSet();
+        let thisPartialElem;
+        for (const referenceId of entity.getReferenceConcreteIds()) {
+            // TODO: probably need to rename from 'id' to 'ref' so these names aren't so ambiguous
+            const referenceIdInTarget = this.context.findTargetEntityId(referenceId);
+            const alreadyImported = core_backend_1.EntityReferences.isValid(referenceIdInTarget);
+            if (alreadyImported)
+                continue;
+            core_bentley_1.Logger.logTrace(loggerCategory, `Deferring resolution of reference '${referenceId}' of element '${entity.id}'`);
+            const referencedExistsInSource = EntityUnifier_1.EntityUnifier.exists(this.sourceDb, { entityReference: referenceId });
+            if (!referencedExistsInSource) {
+                core_bentley_1.Logger.logWarning(loggerCategory, `Source ${EntityUnifier_1.EntityUnifier.getReadableType(entity)} (${entity.id}) has a dangling reference to (${referenceId})`);
+                switch (this._options.danglingReferencesBehavior) {
+                    case "ignore":
+                        continue;
+                    case "reject":
+                        throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NotFound, [
+                            `Found a reference to an element "${referenceId}" that doesn't exist while looking for references of "${entity.id}".`,
+                            "This must have been caused by an upstream application that changed the iModel.",
+                            "You can set the IModelTransformerOptions.danglingReferencesBehavior option to 'ignore' to ignore this, but this will leave the iModel",
+                            "in a state where downstream consuming applications will need to handle the invalidity themselves. In some cases, writing a custom",
+                            "transformer to remove the reference and fix affected elements may be suitable.",
+                        ].join("\n"));
+                }
+            }
+            if (thisPartialElem === undefined) {
+                thisPartialElem = new PartiallyCommittedEntity(missingReferences, this.makePartialEntityCompleter(entity));
+                if (!this._partiallyCommittedEntities.has(entity))
+                    this._partiallyCommittedEntities.set(entity, thisPartialElem);
+            }
+            missingReferences.add(referenceId);
+            const entityReference = core_backend_1.EntityReferences.from(entity);
+            this._pendingReferences.set({ referenced: referenceId, referencer: entityReference }, thisPartialElem);
+        }
+    }
+    /** 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.
+     */
+    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");
+        }
+        return this.exporter.exportElement(sourceElementId);
+    }
+    /** 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.
+     */
+    async processChildElements(sourceElementId) {
+        await this.initialize();
+        return this.exporter.exportChildElements(sourceElementId);
+    }
+    /** 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) { return true; }
+    /**
+     * If they haven't been already, import all of the required references
+     * @internal do not call, override or implement this, it will be removed
+     */
+    async preExportElement(sourceElement) {
+        const elemClass = sourceElement.constructor;
+        const unresolvedReferences = elemClass.requiredReferenceKeys
+            .map((referenceKey) => {
+            const idContainer = sourceElement[referenceKey];
+            const referenceType = elemClass.requiredReferenceKeyTypeMap[referenceKey];
+            // For now we just consider all required references to be elements (as they are in biscore), and do not support
+            // entities that refuse to be inserted without a different kind of entity (e.g. aspect or relationship) first being inserted
+            (0, core_bentley_1.assert)(referenceType === core_common_1.ConcreteEntityTypes.Element || referenceType === core_common_1.ConcreteEntityTypes.Model);
+            return mapId64(idContainer, (id) => {
+                if (id === core_bentley_1.Id64.invalid || id === core_common_1.IModel.rootSubjectId)
+                    return undefined; // not allowed to directly export the root subject
+                if (!this.context.isBetweenIModels) {
+                    // Within the same iModel, can use existing DefinitionElements without remapping
+                    // This is relied upon by the TemplateModelCloner
+                    // TODO: extract this out to only be in the TemplateModelCloner
+                    const asDefinitionElem = this.sourceDb.elements.tryGetElement(id, core_backend_1.DefinitionElement);
+                    if (asDefinitionElem && !(asDefinitionElem instanceof core_backend_1.RecipeDefinitionElement)) {
+                        this.context.remapElement(id, id);
+                    }
+                }
+                return id;
+            })
+                .filter((sourceReferenceId) => {
+                if (sourceReferenceId === undefined)
+                    return false;
+                const referenceInTargetId = this.context.findTargetElementId(sourceReferenceId);
+                const isInTarget = core_bentley_1.Id64.isValid(referenceInTargetId);
+                return !isInTarget;
+            });
+        })
+            .flat();
+        if (unresolvedReferences.length > 0) {
+            for (const reference of unresolvedReferences) {
+                const processState = this.getElemTransformState(reference);
+                // must export element first
+                if (processState.needsElemImport)
+                    await this.exporter.exportElement(reference);
+                if (processState.needsModelImport)
+                    await this.exporter.exportModel(reference);
+            }
+        }
+    }
+    getElemTransformState(elementId) {
+        const dbHasModel = (db, id) => {
+            const maybeModelId = core_backend_1.EntityReferences.fromEntityType(id, core_common_1.ConcreteEntityTypes.Model);
+            return EntityUnifier_1.EntityUnifier.exists(db, { entityReference: maybeModelId });
+        };
+        const isSubModeled = dbHasModel(this.sourceDb, elementId);
+        const idOfElemInTarget = this.context.findTargetElementId(elementId);
+        const isElemInTarget = core_bentley_1.Id64.invalid !== idOfElemInTarget;
+        const needsModelImport = isSubModeled && (!isElemInTarget || !dbHasModel(this.targetDb, idOfElemInTarget));
+        return { needsElemImport: !isElemInTarget, needsModelImport };
+    }
+    /** Override of [IModelExportHandler.onExportElement]($transformer) that imports an element into the target iModel when it is exported from the source iModel.
+     * This override calls [[onTransformElement]] and then [IModelImporter.importElement]($transformer) to update the target iModel.
+     */
+    onExportElement(sourceElement) {
+        var _a;
+        let targetElementId;
+        let targetElementProps;
+        if (this._options.preserveElementIdsForFiltering) {
+            targetElementId = sourceElement.id;
+            targetElementProps = this.onTransformElement(sourceElement);
+        }
+        else if (this._options.wasSourceIModelCopiedToTarget) {
+            targetElementId = sourceElement.id;
+            targetElementProps = this.targetDb.elements.getElementProps(targetElementId);
+        }
+        else {
+            targetElementId = this.context.findTargetElementId(sourceElement.id);
+            targetElementProps = this.onTransformElement(sourceElement);
+        }
+        // if an existing remapping was not yet found, check by Code as long as the CodeScope is valid (invalid means a missing reference so not worth checking)
+        if (!core_bentley_1.Id64.isValidId64(targetElementId) && core_bentley_1.Id64.isValidId64(targetElementProps.code.scope)) {
+            // respond the same way to undefined code value as the @see Code class, but don't use that class because is trims
+            // whitespace from the value, and there are iModels out there with untrimmed whitespace that we ought not to trim
+            targetElementProps.code.value = (_a = targetElementProps.code.value) !== null && _a !== void 0 ? _a : "";
+            targetElementId = this.targetDb.elements.queryElementIdByCode(targetElementProps.code);
+            if (undefined !== targetElementId) {
+                const targetElement = this.targetDb.elements.getElement(targetElementId);
+                if (targetElement.classFullName === targetElementProps.classFullName) { // ensure code remapping doesn't change the target class
+                    this.context.remapElement(sourceElement.id, targetElementId); // record that the targetElement was found by Code
+                }
+                else {
+                    targetElementId = undefined;
+                    targetElementProps.code = core_common_1.Code.createEmpty(); // clear out invalid code
+                }
+            }
+        }
+        if (undefined !== targetElementId && core_bentley_1.Id64.isValidId64(targetElementId)) {
+            // compare LastMod of sourceElement to ExternalSourceAspect of targetElement to see there are changes to import
+            if (!this.hasElementChanged(sourceElement, targetElementId)) {
+                return;
+            }
+        }
+        this.collectUnmappedReferences(sourceElement);
+        // TODO: untangle targetElementId state...
+        if (targetElementId === core_bentley_1.Id64.invalid)
+            targetElementId = undefined;
+        targetElementProps.id = targetElementId; // targetElementId will be valid (indicating update) or undefined (indicating insert)
+        if (!this._options.wasSourceIModelCopiedToTarget) {
+            this.importer.importElement(targetElementProps); // don't need to import if iModel was copied
+        }
+        this.context.remapElement(sourceElement.id, targetElementProps.id); // targetElementProps.id assigned by importElement
+        // now that we've mapped this elem we can fix unmapped references to it
+        this.resolvePendingReferences(sourceElement);
+        if (!this._options.noProvenance) {
+            const aspectProps = this.initElementProvenance(sourceElement.id, targetElementProps.id);
+            let aspectId = this.queryExternalSourceAspectId(aspectProps);
+            if (aspectId === undefined) {
+                aspectId = this.provenanceDb.elements.insertAspect(aspectProps);
+            }
+            else {
+                this.provenanceDb.elements.updateAspect(aspectProps);
+            }
+            aspectProps.id = aspectId;
+            this.markLastProvenance(aspectProps, { isRelationship: false });
+        }
+    }
+    resolvePendingReferences(entity) {
+        for (const referencer of this._pendingReferences.getReferencers(entity)) {
+            const key = PendingReferenceMap_1.PendingReference.from(referencer, entity);
+            const pendingRef = this._pendingReferences.get(key);
+            if (!pendingRef)
+                continue;
+            pendingRef.resolveReference(core_backend_1.EntityReferences.from(entity));
+            this._pendingReferences.delete(key);
+        }
+    }
+    /** Override of [IModelExportHandler.onDeleteElement]($transformer) that is called when [IModelExporter]($transformer) detects that an Element has been deleted from the source iModel.
+     * This override propagates the delete to the target iModel via [IModelImporter.deleteElement]($transformer).
+     */
+    onDeleteElement(sourceElementId) {
+        const targetElementId = this.context.findTargetElementId(sourceElementId);
+        if (core_bentley_1.Id64.isValidId64(targetElementId)) {
+            this.importer.deleteElement(targetElementId);
+        }
+    }
+    /** Override of [IModelExportHandler.onExportModel]($transformer) that is called when a Model should be exported from the source iModel.
+     * This override calls [[onTransformModel]] and then [IModelImporter.importModel]($transformer) to update the target iModel.
+     */
+    onExportModel(sourceModel) {
+        if (core_common_1.IModel.repositoryModelId === sourceModel.id) {
+            return; // The RepositoryModel should not be directly imported
+        }
+        const targetModeledElementId = this.context.findTargetElementId(sourceModel.id);
+        const targetModelProps = this.onTransformModel(sourceModel, targetModeledElementId);
+        this.importer.importModel(targetModelProps);
+        this.resolvePendingReferences(sourceModel);
+    }
+    /** Override of [IModelExportHandler.onDeleteModel]($transformer) that is called when [IModelExporter]($transformer) detects that a [Model]($backend) has been deleted from the source iModel. */
+    onDeleteModel(sourceModelId) {
+        // 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, [[remapDeletedSourceElements]] will find and remap the deleted element making this operation valid
+        const targetModelId = this.context.findTargetElementId(sourceModelId);
+        if (core_bentley_1.Id64.isValidId64(targetModelId)) {
+            this.importer.deleteModel(targetModelId);
+        }
+    }
+    /** 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.
+     */
+    async processModel(sourceModeledElementId) {
+        await this.initialize();
+        return this.exporter.exportModel(sourceModeledElementId);
+    }
+    /** 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.
+     */
+    async processModelContents(sourceModelId, targetModelId, elementClassFullName = core_backend_1.Element.classFullName) {
+        await this.initialize();
+        this.targetDb.models.getModel(targetModelId); // throws if Model does not exist
+        this.context.remapElement(sourceModelId, targetModelId); // set remapping in case importModelContents is called directly
+        return this.exporter.exportModelContents(sourceModelId, elementClassFullName);
+    }
+    /** Cause all sub-models that recursively descend from the specified Subject to be exported from the source iModel and imported into the target iModel. */
+    async processSubjectSubModels(sourceSubjectId) {
+        await this.initialize();
+        // import DefinitionModels first
+        const childDefinitionPartitionSql = `SELECT ECInstanceId FROM ${core_backend_1.DefinitionPartition.classFullName} WHERE Parent.Id=:subjectId`;
+        await this.sourceDb.withPreparedStatement(childDefinitionPartitionSql, async (statement) => {
+            statement.bindId("subjectId", sourceSubjectId);
+            while (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) {
+                await this.processModel(statement.getValue(0).getId());
+            }
+        });
+        // import other partitions next
+        const childPartitionSql = `SELECT ECInstanceId FROM ${core_backend_1.InformationPartitionElement.classFullName} WHERE Parent.Id=:subjectId`;
+        await this.sourceDb.withPreparedStatement(childPartitionSql, async (statement) => {
+            statement.bindId("subjectId", sourceSubjectId);
+            while (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) {
+                const modelId = statement.getValue(0).getId();
+                const model = this.sourceDb.models.getModel(modelId);
+                if (!(model instanceof core_backend_1.DefinitionModel)) {
+                    await this.processModel(modelId);
+                }
+            }
+        });
+        // recurse into child Subjects
+        const childSubjectSql = `SELECT ECInstanceId FROM ${core_backend_1.Subject.classFullName} WHERE Parent.Id=:subjectId`;
+        await this.sourceDb.withPreparedStatement(childSubjectSql, async (statement) => {
+            statement.bindId("subjectId", sourceSubjectId);
+            while (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) {
+                await this.processSubjectSubModels(statement.getValue(0).getId());
+            }
+        });
+    }
+    /** Transform the specified sourceModel into ModelProps for the target iModel.
+     * @param sourceModel The Model from the source iModel to be transformed.
+     * @param targetModeledElementId The transformed Model will *break down* or *detail* this Element in the target iModel.
+     * @returns ModelProps for the target iModel.
+     * @note A subclass can override this method to provide custom transform behavior.
+     */
+    onTransformModel(sourceModel, targetModeledElementId) {
+        const targetModelProps = sourceModel.toJSON();
+        // don't directly edit deep object since toJSON performs a shallow clone
+        targetModelProps.modeledElement = { ...targetModelProps.modeledElement, id: targetModeledElementId };
+        targetModelProps.id = targetModeledElementId;
+        targetModelProps.parentModel = this.context.findTargetElementId(targetModelProps.parentModel);
+        return targetModelProps;
+    }
+    /** Import elements that were deferred in a prior pass.
+     * @deprecated in 3.x. This method is no longer necessary since the transformer no longer needs to defer elements
+     */
+    async processDeferredElements(_numRetries = 3) { }
+    finalizeTransformation() {
+        if (this._partiallyCommittedEntities.size > 0) {
+            core_bentley_1.Logger.logWarning(loggerCategory, [
+                "The following elements were never fully resolved:",
+                [...this._partiallyCommittedEntities.keys()].join(","),
+                "This indicates that either some references were excluded from the transformation",
+                "or the source has dangling references.",
+            ].join("\n"));
+            for (const partiallyCommittedElem of this._partiallyCommittedEntities.values()) {
+                partiallyCommittedElem.forceComplete();
+            }
+        }
+    }
+    /** 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.
+     */
+    async processRelationships(baseRelClassFullName) {
+        await this.initialize();
+        return this.exporter.exportRelationships(baseRelClassFullName);
+    }
+    /** Override of [IModelExportHandler.shouldExportRelationship]($transformer) that is called to determine if a [Relationship]($backend) should be exported.
+     * @note Reaching this point means that the relationship has passed the standard exclusion checks in [IModelExporter]($transformer).
+     */
+    shouldExportRelationship(_sourceRelationship) { return true; }
+    /** Override of [IModelExportHandler.onExportRelationship]($transformer) that imports a relationship into the target iModel when it is exported from the source iModel.
+     * This override calls [[onTransformRelationship]] and then [IModelImporter.importRelationship]($transformer) to update the target iModel.
+     */
+    onExportRelationship(sourceRelationship) {
+        const targetRelationshipProps = this.onTransformRelationship(sourceRelationship);
+        const targetRelationshipInstanceId = this.importer.importRelationship(targetRelationshipProps);
+        if (!this._options.noProvenance && core_bentley_1.Id64.isValidId64(targetRelationshipInstanceId)) {
+            const aspectProps = this.initRelationshipProvenance(sourceRelationship, targetRelationshipInstanceId);
+            if (undefined === aspectProps.id) {
+                aspectProps.id = this.provenanceDb.elements.insertAspect(aspectProps);
+            }
+            (0, core_bentley_1.assert)(aspectProps.id !== undefined);
+            this.markLastProvenance(aspectProps, { isRelationship: true });
+        }
+    }
+    /** Override of [IModelExportHandler.onDeleteRelationship]($transformer) that is called when [IModelExporter]($transformer) detects that a [Relationship]($backend) has been deleted from the source iModel.
+     * This override propagates the delete to the target iModel via [IModelImporter.deleteRelationship]($transformer).
+     */
+    onDeleteRelationship(sourceRelInstanceId) {
+        const sql = `SELECT ECInstanceId,JsonProperties FROM ${core_backend_1.ExternalSourceAspect.classFullName} aspect` +
+            ` WHERE aspect.Scope.Id=:scopeId AND aspect.Kind=:kind AND aspect.Identifier=:identifier LIMIT 1`;
+        this.targetDb.withPreparedStatement(sql, (statement) => {
+            statement.bindId("scopeId", this.targetScopeElementId);
+            statement.bindString("kind", core_backend_1.ExternalSourceAspect.Kind.Relationship);
+            statement.bindString("identifier", sourceRelInstanceId);
+            if (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) {
+                const json = JSON.parse(statement.getValue(1).getString());
+                if (undefined !== json.targetRelInstanceId) {
+                    const targetRelationship = this.targetDb.relationships.tryGetInstance(core_backend_1.ElementRefersToElements.classFullName, json.targetRelInstanceId);
+                    if (targetRelationship) {
+                        this.importer.deleteRelationship(targetRelationship.toJSON());
+                    }
+                    this.targetDb.elements.deleteAspect(statement.getValue(0).getId());
+                }
+            }
+        });
+    }
+    /** Detect Relationship deletes using ExternalSourceAspects in the target iModel and a *brute force* comparison against relationships in the source iModel.
+     * @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.
+     * @throws [[IModelError]] If the required provenance information is not available to detect deletes.
+     */
+    async detectRelationshipDeletes() {
+        if (this._options.isReverseSynchronization) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.BadRequest, "Cannot detect deletes when isReverseSynchronization=true");
+        }
+        const aspectDeleteIds = [];
+        const sql = `SELECT ECInstanceId,Identifier,JsonProperties FROM ${core_backend_1.ExternalSourceAspect.classFullName} aspect WHERE aspect.Scope.Id=:scopeId AND aspect.Kind=:kind`;
+        await this.targetDb.withPreparedStatement(sql, async (statement) => {
+            statement.bindId("scopeId", this.targetScopeElementId);
+            statement.bindString("kind", core_backend_1.ExternalSourceAspect.Kind.Relationship);
+            while (core_bentley_1.DbResult.BE_SQLITE_ROW === statement.step()) {
+                const sourceRelInstanceId = core_bentley_1.Id64.fromJSON(statement.getValue(1).getString());
+                if (undefined === this.sourceDb.relationships.tryGetInstanceProps(core_backend_1.ElementRefersToElements.classFullName, sourceRelInstanceId)) {
+                    const json = JSON.parse(statement.getValue(2).getString());
+                    if (undefined !== json.targetRelInstanceId) {
+                        const targetRelationship = this.targetDb.relationships.getInstance(core_backend_1.ElementRefersToElements.classFullName, json.targetRelInstanceId);
+                        this.importer.deleteRelationship(targetRelationship.toJSON());
+                    }
+                    aspectDeleteIds.push(statement.getValue(0).getId());
+                }
+                await this._yieldManager.allowYield();
+            }
+        });
+        this.targetDb.elements.deleteAspect(aspectDeleteIds);
+    }
+    /** Transform the specified sourceRelationship into RelationshipProps for the target iModel.
+     * @param sourceRelationship The Relationship from the source iModel to be transformed.
+     * @returns RelationshipProps for the target iModel.
+     * @note A subclass can override this method to provide custom transform behavior.
+     */
+    onTransformRelationship(sourceRelationship) {
+        const targetRelationshipProps = sourceRelationship.toJSON();
+        targetRelationshipProps.sourceId = this.context.findTargetElementId(sourceRelationship.sourceId);
+        targetRelationshipProps.targetId = this.context.findTargetElementId(sourceRelationship.targetId);
+        sourceRelationship.forEachProperty((propertyName, propertyMetaData) => {
+            if ((core_common_1.PrimitiveTypeCode.Long === propertyMetaData.primitiveType) && ("Id" === propertyMetaData.extendedType)) {
+                targetRelationshipProps[propertyName] = this.context.findTargetElementId(sourceRelationship.asAny[propertyName]);
+            }
+        });
+        return targetRelationshipProps;
+    }
+    /** Override of [IModelExportHandler.onExportElementUniqueAspect]($transformer) that imports an ElementUniqueAspect into the target iModel when it is exported from the source iModel.
+     * This override calls [[onTransformElementAspect]] and then [IModelImporter.importElementUniqueAspect]($transformer) to update the target iModel.
+     */
+    onExportElementUniqueAspect(sourceAspect) {
+        const targetElementId = this.context.findTargetElementId(sourceAspect.element.id);
+        const targetAspectProps = this.onTransformElementAspect(sourceAspect, targetElementId);
+        this.collectUnmappedReferences(sourceAspect);
+        const targetId = this.importer.importElementUniqueAspect(targetAspectProps);
+        this.context.remapElementAspect(sourceAspect.id, targetId);
+        this.resolvePendingReferences(sourceAspect);
+    }
+    /** Override of [IModelExportHandler.onExportElementMultiAspects]($transformer) that imports ElementMultiAspects into the target iModel when they are exported from the source iModel.
+     * This override calls [[onTransformElementAspect]] for each ElementMultiAspect and then [IModelImporter.importElementMultiAspects]($transformer) to update the target iModel.
+     * @note ElementMultiAspects are handled as a group to make it easier to differentiate between insert, update, and delete.
+     */
+    onExportElementMultiAspects(sourceAspects) {
+        const targetElementId = this.context.findTargetElementId(sourceAspects[0].element.id);
+        // Transform source ElementMultiAspects into target ElementAspectProps
+        const targetAspectPropsArray = sourceAspects.map((srcA) => this.onTransformElementAspect(srcA, targetElementId));
+        sourceAspects.forEach((a) => this.collectUnmappedReferences(a));
+        // const targetAspectsToImport = targetAspectPropsArray.filter((targetAspect, i) => hasEntityChanged(sourceAspects[i], targetAspect));
+        const targetIds = this.importer.importElementMultiAspects(targetAspectPropsArray, (a) => {
+            var _a;
+            const isExternalSourceAspectFromTransformer = a instanceof core_backend_1.ExternalSourceAspect && ((_a = a.scope) === null || _a === void 0 ? void 0 : _a.id) === this.targetScopeElementId;
+            return !this._options.includeSourceProvenance || !isExternalSourceAspectFromTransformer;
+        });
+        for (let i = 0; i < targetIds.length; ++i) {
+            this.context.remapElementAspect(sourceAspects[i].id, targetIds[i]);
+            this.resolvePendingReferences(sourceAspects[i]);
+        }
+    }
+    /** Transform the specified sourceElementAspect into ElementAspectProps for the target iModel.
+     * @param sourceElementAspect The ElementAspect from the source iModel to be transformed.
+     * @param _targetElementId The ElementId of the target Element that will own the ElementAspects after transformation.
+     * @returns ElementAspectProps for the target iModel.
+     * @note A subclass can override this method to provide custom transform behavior.
+     */
+    onTransformElementAspect(sourceElementAspect, _targetElementId) {
+        const targetElementAspectProps = this.context.cloneElementAspect(sourceElementAspect);
+        return targetElementAspectProps;
+    }
+    /** Override of [IModelExportHandler.shouldExportSchema]($transformer) that is called to determine if a schema should be exported
+     * @note the default behavior doesn't import schemas older than those already in the target
+     */
+    shouldExportSchema(schemaKey) {
+        const versionInTarget = this.targetDb.querySchemaVersion(schemaKey.name);
+        if (versionInTarget === undefined)
+            return true;
+        return Semver.gt(`${schemaKey.version.read}.${schemaKey.version.write}.${schemaKey.version.minor}`, core_backend_1.Schema.toSemverString(versionInTarget));
+    }
+    /** Override of [IModelExportHandler.onExportSchema]($transformer) that serializes a schema to disk for [[processSchemas]] to import into
+     * the target iModel when it is exported from the source iModel.
+     * @returns {Promise<ExportSchemaResult>} Although the type is possibly void for backwards compatibility of subclasses,
+     *                                        `IModelTransformer.onExportSchema` always returns an[[IModelExportHandler.ExportSchemaResult]]
+     *                                        with a defined `schemaPath` property, for subclasses to know where the schema was written.
+     *                                        Schemas are *not* guaranteed to be written to [[IModelTransformer._schemaExportDir]] by a
+     *                                        known pattern derivable from the schema's name, so you must use this to find it.
+     */
+    async onExportSchema(schema) {
+        const ext = ".ecschema.xml";
+        let schemaFileName = schema.name + ext;
+        // many file systems have a max file-name/path-segment size of 255, so we workaround that on all systems
+        const systemMaxPathSegmentSize = 255;
+        if (schemaFileName.length > systemMaxPathSegmentSize) {
+            // this name should be well under 255 bytes
+            // ( 100 + (Number.MAX_SAFE_INTEGER.toString().length = 16) + (ext.length = 13) ) = 129 which is less than 255
+            // You'd have to be past 2**53-1 (Number.MAX_SAFE_INTEGER) long named schemas in order to hit decimal formatting,
+            // and that's on the scale of at least petabytes. `Map.prototype.size` shouldn't return floating points, and even
+            // if they do they're in scientific notation, size bound and contain no invalid windows path chars
+            schemaFileName = `${schema.name.slice(0, 100)}${this._longNamedSchemasMap.size}${ext}`;
+            nodeAssert(schemaFileName.length <= systemMaxPathSegmentSize, "Schema name was still long. This is a bug.");
+            this._longNamedSchemasMap.set(schema.name, schemaFileName);
+        }
+        this.sourceDb.nativeDb.exportSchema(schema.name, this._schemaExportDir, schemaFileName);
+        return { schemaPath: path.join(this._schemaExportDir, schemaFileName) };
+    }
+    _makeLongNameResolvingSchemaCtx() {
+        const result = new core_backend_1.ECSchemaXmlContext();
+        result.setSchemaLocater((key) => {
+            const match = this._longNamedSchemasMap.get(key.name);
+            if (match !== undefined)
+                return path.join(this._schemaExportDir, match);
+            return undefined;
+        });
+        return result;
+    }
+    /** Cause all schemas to be exported from the source iModel and imported into the target iModel.
+     * @note For performance reasons, it is recommended that [IModelDb.saveChanges]($backend) be called after `processSchemas` is complete.
+     * It is more efficient to process *data* changes after the schema changes have been saved.
+     */
+    async processSchemas() {
+        // we do not need to initialize for this since no entities are exported
+        try {
+            core_backend_1.IModelJsFs.mkdirSync(this._schemaExportDir);
+            this._longNamedSchemasMap.clear();
+            await this.exporter.exportSchemas();
+            const exportedSchemaFiles = core_backend_1.IModelJsFs.readdirSync(this._schemaExportDir);
+            if (exportedSchemaFiles.length === 0)
+                return;
+            const schemaFullPaths = exportedSchemaFiles.map((s) => path.join(this._schemaExportDir, s));
+            const maybeLongNameResolvingSchemaCtx = this._longNamedSchemasMap.size > 0
+                ? this._makeLongNameResolvingSchemaCtx()
+                : undefined;
+            return await this.targetDb.importSchemas(schemaFullPaths, { ecSchemaXmlContext: maybeLongNameResolvingSchemaCtx });
+        }
+        finally {
+            core_backend_1.IModelJsFs.removeSync(this._schemaExportDir);
+            this._longNamedSchemasMap.clear();
+        }
+    }
+    /** 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.
+   */
+    async processFonts() {
+        // we do not need to initialize for this since no entities are exported
+        await this.initialize();
+        return this.exporter.exportFonts();
+    }
+    /** Override of [IModelExportHandler.onExportFont]($transformer) that imports a font into the target iModel when it is exported from the source iModel. */
+    onExportFont(font, _isUpdate) {
+        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.
+     */
+    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.
+     */
+    async processCodeSpec(codeSpecName) {
+        await this.initialize();
+        return this.exporter.exportCodeSpecByName(codeSpecName);
+    }
+    /** Override of [IModelExportHandler.shouldExportCodeSpec]($transformer) that is called to determine if a CodeSpec should be exported from the source iModel.
+     * @note Reaching this point means that the CodeSpec has passed the standard exclusion checks in [IModelExporter]($transformer).
+     */
+    shouldExportCodeSpec(_sourceCodeSpec) { return true; }
+    /** Override of [IModelExportHandler.onExportCodeSpec]($transformer) that imports a CodeSpec into the target iModel when it is exported from the source iModel. */
+    onExportCodeSpec(sourceCodeSpec) {
+        this.context.importCodeSpec(sourceCodeSpec.id);
+    }
+    /** Recursively import all Elements and sub-Models that descend from the specified Subject */
+    async processSubject(sourceSubjectId, targetSubjectId) {
+        await this.initialize();
+        this.sourceDb.elements.getElement(sourceSubjectId, core_backend_1.Subject); // throws if sourceSubjectId is not a Subject
+        this.targetDb.elements.getElement(targetSubjectId, core_backend_1.Subject); // throws if targetSubjectId is not a Subject
+        this.context.remapElement(sourceSubjectId, targetSubjectId);
+        await this.processChildElements(sourceSubjectId);
+        await this.processSubjectSubModels(sourceSubjectId);
+        return this.processDeferredElements(); // eslint-disable-line deprecation/deprecation
+    }
+    /**
+     * Initialize prerequisites of processing, you must initialize with an [[InitFromExternalSourceAspectsArgs]] if you
+     * are intending process changes, but prefer using [[processChanges]]
+     * Called by all `process*` functions implicitly.
+     * Overriders must call `super.initialize()` first
+     */
+    async initialize(args) {
+        if (this._initialized)
+            return;
+        await this.context.initialize();
+        // eslint-disable-next-line deprecation/deprecation
+        await this.initFromExternalSourceAspects(args);
+        this._initialized = true;
+    }
+    /** 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() {
+        core_bentley_1.Logger.logTrace(loggerCategory, "processAll()");
+        this.logSettings();
+        this.validateScopeProvenance();
+        await this.initialize();
+        await this.exporter.exportCodeSpecs();
+        await this.exporter.exportFonts();
+        // The RepositoryModel and root Subject of the target iModel should not be transformed.
+        await this.exporter.exportChildElements(core_common_1.IModel.rootSubjectId); // start below the root Subject
+        await this.exporter.exportModelContents(core_common_1.IModel.repositoryModelId, core_backend_1.Element.classFullName, true); // after the Subject hierarchy, process the other elements of the RepositoryModel
+        await this.exporter.exportSubModels(core_common_1.IModel.repositoryModelId); // start below the RepositoryModel
+        await this.exporter.exportRelationships(core_backend_1.ElementRefersToElements.classFullName);
+        await this.processDeferredElements(); // eslint-disable-line deprecation/deprecation
+        if (this.shouldDetectDeletes()) {
+            await this.detectElementDeletes();
+            await this.detectRelationshipDeletes();
+        }
+        if (this._options.optimizeGeometry)
+            this.importer.optimizeGeometry(this._options.optimizeGeometry);
+        this.importer.computeProjectExtents();
+        this.finalizeTransformation();
+    }
+    markLastProvenance(sourceAspect, { isRelationship = false }) {
+        var _a;
+        this._lastProvenanceEntityInfo = {
+            entityId: sourceAspect.element.id,
+            aspectId: sourceAspect.id,
+            aspectVersion: (_a = sourceAspect.version) !== null && _a !== void 0 ? _a : "",
+            aspectKind: isRelationship ? core_backend_1.ExternalSourceAspect.Kind.Relationship : core_backend_1.ExternalSourceAspect.Kind.Element,
+        };
+    }
+    /**
+     * 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
+     */
+    loadStateFromDb(db) {
+        const lastProvenanceEntityInfo = db.withSqliteStatement(`SELECT entityId, aspectId, aspectVersion, aspectKind FROM ${IModelTransformer.lastProvenanceEntityInfoTable}`, (stmt) => {
+            if (core_bentley_1.DbResult.BE_SQLITE_ROW !== stmt.step())
+                throw Error("expected row when getting lastProvenanceEntityId from target state table");
+            return {
+                entityId: stmt.getValueString(0),
+                aspectId: stmt.getValueString(1),
+                aspectVersion: stmt.getValueString(2),
+                aspectKind: stmt.getValueString(3),
+            };
+        });
+        const targetHasCorrectLastProvenance = 
+        // ignore provenance check if it's null since we can't bind those ids
+        !core_bentley_1.Id64.isValidId64(lastProvenanceEntityInfo.aspectId) ||
+            !core_bentley_1.Id64.isValidId64(lastProvenanceEntityInfo.entityId) ||
+            this.provenanceDb.withPreparedStatement(`
+        SELECT Version FROM ${core_backend_1.ExternalSourceAspect.classFullName}
+        WHERE Scope.Id=:scopeId
+          AND ECInstanceId=:aspectId
+          AND Kind=:kind
+          AND Element.Id=:entityId
+      `, (statement) => {
+                statement.bindId("scopeId", this.targetScopeElementId);
+                statement.bindId("aspectId", lastProvenanceEntityInfo.aspectId);
+                statement.bindString("kind", lastProvenanceEntityInfo.aspectKind);
+                statement.bindId("entityId", lastProvenanceEntityInfo.entityId);
+                const stepResult = statement.step();
+                switch (stepResult) {
+                    case core_bentley_1.DbResult.BE_SQLITE_ROW:
+                        const version = statement.getValue(0).getString();
+                        return version === lastProvenanceEntityInfo.aspectVersion;
+                    case core_bentley_1.DbResult.BE_SQLITE_DONE:
+                        return false;
+                    default:
+                        throw new core_common_1.IModelError(core_bentley_1.IModelStatus.SQLiteError, `got sql error ${stepResult}`);
+                }
+            });
+        if (!targetHasCorrectLastProvenance)
+            throw Error([
+                "Target for resuming from does not have the expected provenance ",
+                "from the target that the resume state was made with",
+            ].join("\n"));
+        this._lastProvenanceEntityInfo = lastProvenanceEntityInfo;
+        const state = db.withSqliteStatement(`SELECT data FROM ${IModelTransformer.jsStateTable}`, (stmt) => {
+            if (core_bentley_1.DbResult.BE_SQLITE_ROW !== stmt.step())
+                throw Error("expected row when getting data from js state table");
+            return JSON.parse(stmt.getValueString(0));
+        });
+        if (state.transformerClass !== this.constructor.name)
+            throw Error("resuming from a differently named transformer class, it is not necessarily valid to resume with a different transformer class");
+        // force assign to readonly options since we do not know how the transformer subclass takes options to pass to the superclass
+        this._options = state.options;
+        this.context.loadStateFromDb(db);
+        this.importer.loadStateFromJson(state.importerState);
+        this.exporter.loadStateFromJson(state.exporterState);
+        this.loadAdditionalStateJson(state.additionalState);
+    }
+    /**
+     * 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(statePath, ...constructorArgs) {
+        const transformer = new this(...constructorArgs);
+        const db = new core_backend_1.SQLiteDb();
+        db.openDb(statePath, core_bentley_1.OpenMode.Readonly);
+        try {
+            transformer.loadStateFromDb(db);
+        }
+        finally {
+            db.closeDb();
+        }
+        return transformer;
+    }
+    /**
+     * You may override this to store arbitrary json state in a transformer state dump, useful for some resumptions
+     * @see [[IModelTransformer.saveStateToFile]]
+     */
+    getAdditionalStateJson() {
+        return {};
+    }
+    /**
+     * You may override this to load arbitrary json state in a transformer state dump, useful for some resumptions
+     * @see [[IModelTransformer.loadStateFromFile]]
+     */
+    loadAdditionalStateJson(_additionalState) { }
+    /**
+     * 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
+     */
+    saveStateToDb(db) {
+        const jsonState = {
+            transformerClass: this.constructor.name,
+            options: this._options,
+            importerState: this.importer.saveStateToJson(),
+            exporterState: this.exporter.saveStateToJson(),
+            additionalState: this.getAdditionalStateJson(),
+        };
+        this.context.saveStateToDb(db);
+        if (core_bentley_1.DbResult.BE_SQLITE_DONE !== db.executeSQL(`CREATE TABLE ${IModelTransformer.jsStateTable} (data TEXT)`))
+            throw Error("Failed to create the js state table in the state database");
+        if (core_bentley_1.DbResult.BE_SQLITE_DONE !== db.executeSQL(`
+      CREATE TABLE ${IModelTransformer.lastProvenanceEntityInfoTable} (
+        -- because we cannot bind the invalid id which we use for our null state, we actually store the id as a hex string
+        entityId TEXT,
+        aspectId TEXT,
+        aspectVersion TEXT,
+        aspectKind TEXT
+      )
+    `))
+            throw Error("Failed to create the target state table in the state database");
+        db.saveChanges();
+        db.withSqliteStatement(`INSERT INTO ${IModelTransformer.jsStateTable} (data) VALUES (?)`, (stmt) => {
+            stmt.bindString(1, JSON.stringify(jsonState));
+            if (core_bentley_1.DbResult.BE_SQLITE_DONE !== stmt.step())
+                throw Error("Failed to insert options into the state database");
+        });
+        db.withSqliteStatement(`INSERT INTO ${IModelTransformer.lastProvenanceEntityInfoTable} (entityId, aspectId, aspectVersion, aspectKind) VALUES (?,?,?,?)`, (stmt) => {
+            stmt.bindString(1, this._lastProvenanceEntityInfo.entityId);
+            stmt.bindString(2, this._lastProvenanceEntityInfo.aspectId);
+            stmt.bindString(3, this._lastProvenanceEntityInfo.aspectVersion);
+            stmt.bindString(4, this._lastProvenanceEntityInfo.aspectKind);
+            if (core_bentley_1.DbResult.BE_SQLITE_DONE !== stmt.step())
+                throw Error("Failed to insert options into the state database");
+        });
+        db.saveChanges();
+    }
+    /**
+     * 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) {
+        const db = new core_backend_1.SQLiteDb();
+        if (core_backend_1.IModelJsFs.existsSync(nativeStatePath))
+            core_backend_1.IModelJsFs.unlinkSync(nativeStatePath);
+        db.createDb(nativeStatePath);
+        try {
+            this.saveStateToDb(db);
+            db.saveChanges();
+        }
+        finally {
+            db.closeDb();
+        }
+    }
+    /** 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).
+   * @param accessToken A valid access token string
+   * @param startChangesetId Include changes from this changeset up through and including the current changeset.
+   * If this parameter is not provided, then just the current changeset will be exported.
+   * @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(accessToken, startChangesetId) {
+        core_bentley_1.Logger.logTrace(loggerCategory, "processChanges()");
+        this.logSettings();
+        this.validateScopeProvenance();
+        await this.initialize({ accessToken, startChangesetId });
+        await this.exporter.exportChanges(accessToken, startChangesetId);
+        await this.processDeferredElements(); // eslint-disable-line deprecation/deprecation
+        if (this._options.optimizeGeometry)
+            this.importer.optimizeGeometry(this._options.optimizeGeometry);
+        this.importer.computeProjectExtents();
+        this.finalizeTransformation();
+    }
+}
+exports.IModelTransformer = IModelTransformer;
+/** @internal the name of the table where javascript state of the transformer is serialized in transformer state dumps */
+IModelTransformer.jsStateTable = "TransformerJsState";
+/** @internal the name of the table where the target state heuristics is serialized in transformer state dumps */
+IModelTransformer.lastProvenanceEntityInfoTable = "LastProvenanceEntityInfo";
+/** IModelTransformer that clones the contents of a template model.
+ * @beta
+ */
+class TemplateModelCloner extends IModelTransformer {
+    /** Construct a new TemplateModelCloner
+     * @param sourceDb The source IModelDb that contains the templates to clone
+     * @param targetDb Optionally specify the target IModelDb where the cloned template will be inserted.
+     *                 Typically this is left unspecified, and the default is to use the sourceDb as the target
+     * @note The expectation is that the template definitions are within the same iModel where instances will be placed.
+     */
+    constructor(sourceDb, targetDb = sourceDb) {
+        const target = new IModelImporter_1.IModelImporter(targetDb, {
+            autoExtendProjectExtents: false, // autoExtendProjectExtents is intended for transformation service use cases, not template --> instance cloning
+        });
+        super(sourceDb, target, { noProvenance: true }); // WIP: need to decide the proper way to handle provenance
+    }
+    /** Place a template from the sourceDb at the specified placement in the target model within the targetDb.
+     * @param sourceTemplateModelId The Id of the template model in the sourceDb
+     * @param targetModelId The Id of the target model (must be a subclass of GeometricModel3d) where the cloned component will be inserted.
+     * @param placement The placement for the cloned component.
+     * @note *Required References* like the SpatialCategory must be remapped before calling this method.
+     * @returns The mapping of sourceElementIds from the template model to the instantiated targetElementIds in the targetDb in case further processing is required.
+     */
+    async placeTemplate3d(sourceTemplateModelId, targetModelId, placement) {
+        this.context.remapElement(sourceTemplateModelId, targetModelId);
+        this._transform3d = core_geometry_1.Transform.createOriginAndMatrix(placement.origin, placement.angles.toMatrix3d());
+        this._sourceIdToTargetIdMap = new Map();
+        await this.exporter.exportModelContents(sourceTemplateModelId);
+        // Note: the source --> target mapping was needed during the template model cloning phase (remapping parent/child, for example), but needs to be reset afterwards
+        for (const sourceElementId of this._sourceIdToTargetIdMap.keys()) {
+            const targetElementId = this.context.findTargetElementId(sourceElementId);
+            this._sourceIdToTargetIdMap.set(sourceElementId, targetElementId);
+            this.context.removeElement(sourceElementId); // clear the underlying native remapping context for the next clone operation
+        }
+        return this._sourceIdToTargetIdMap; // return the sourceElementId -> targetElementId Map in case further post-processing is required.
+    }
+    /** Place a template from the sourceDb at the specified placement in the target model within the targetDb.
+     * @param sourceTemplateModelId The Id of the template model in the sourceDb
+     * @param targetModelId The Id of the target model (must be a subclass of GeometricModel2d) where the cloned component will be inserted.
+     * @param placement The placement for the cloned component.
+     * @note *Required References* like the DrawingCategory must be remapped before calling this method.
+     * @returns The mapping of sourceElementIds from the template model to the instantiated targetElementIds in the targetDb in case further processing is required.
+     */
+    async placeTemplate2d(sourceTemplateModelId, targetModelId, placement) {
+        this.context.remapElement(sourceTemplateModelId, targetModelId);
+        this._transform3d = core_geometry_1.Transform.createOriginAndMatrix(core_geometry_1.Point3d.createFrom(placement.origin), placement.rotation);
+        this._sourceIdToTargetIdMap = new Map();
+        await this.exporter.exportModelContents(sourceTemplateModelId);
+        // Note: the source --> target mapping was needed during the template model cloning phase (remapping parent/child, for example), but needs to be reset afterwards
+        for (const sourceElementId of this._sourceIdToTargetIdMap.keys()) {
+            const targetElementId = this.context.findTargetElementId(sourceElementId);
+            this._sourceIdToTargetIdMap.set(sourceElementId, targetElementId);
+            this.context.removeElement(sourceElementId); // clear the underlying native remapping context for the next clone operation
+        }
+        return this._sourceIdToTargetIdMap; // return the sourceElementId -> targetElementId Map in case further post-processing is required.
+    }
+    /** Cloning from a template requires this override of onTransformElement. */
+    onTransformElement(sourceElement) {
+        const referenceIds = sourceElement.getReferenceIds();
+        referenceIds.forEach((referenceId) => {
+            if (core_bentley_1.Id64.invalid === this.context.findTargetElementId(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`);
+                }
+                else {
+                    const definitionElement = this.sourceDb.elements.tryGetElement(referenceId, core_backend_1.DefinitionElement);
+                    if (definitionElement && !(definitionElement instanceof core_backend_1.RecipeDefinitionElement)) {
+                        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`);
+                    }
+                }
+            }
+        });
+        const targetElementProps = super.onTransformElement(sourceElement);
+        targetElementProps.federationGuid = core_bentley_1.Guid.createValue(); // clone from template should create a new federationGuid
+        targetElementProps.code = core_common_1.Code.createEmpty(); // clone from template should not maintain codes
+        if (sourceElement instanceof core_backend_1.GeometricElement3d) {
+            const placement = core_common_1.Placement3d.fromJSON(targetElementProps.placement);
+            if (placement.isValid) {
+                placement.multiplyTransform(this._transform3d);
+                targetElementProps.placement = placement;
+            }
+        }
+        else if (sourceElement instanceof core_backend_1.GeometricElement2d) {
+            const placement = core_common_1.Placement2d.fromJSON(targetElementProps.placement);
+            if (placement.isValid) {
+                placement.multiplyTransform(this._transform3d);
+                targetElementProps.placement = placement;
+            }
+        }
+        this._sourceIdToTargetIdMap.set(sourceElement.id, core_bentley_1.Id64.invalid); // keep track of (source) elementIds from the template model, but the target hasn't been inserted yet
+        return targetElementProps;
+    }
+}
+exports.TemplateModelCloner = TemplateModelCloner;
+//# sourceMappingURL=IModelTransformer.js.map