@itwin/imodel-transformer 2.0.0-dev.2 → 2.0.0-dev.20

package/lib/cjs/ProvenanceManager.d.ts

@@ -0,0 +1,159 @@
+import { Id64String } from "@itwin/core-bentley";
+import { type Entity, ExternalSourceAspect, IModelDb } from "@itwin/core-backend";
+import { ChangesetIndexAndId, ExternalSourceAspectProps } from "@itwin/core-common";
+import type { IModelTransformOptions } from "./IModelTransformer";
+import type { SyncTypeResolver } from "./SyncTypeResolver";
+import type { IModelCloneContext } from "./IModelCloneContext";
+/**
+ * Manages provenance scope aspects and synchronization versioning.
+ * Encapsulates all ESA scope management, sync version tracking, and
+ * provenance DB direction logic extracted from IModelTransformer.
+ * @internal
+ */
+export declare class ProvenanceManager {
+    readonly context: IModelCloneContext;
+    private readonly _targetScopeElementId;
+    private readonly _transformerOptions;
+    private readonly _syncTypeResolver;
+    private readonly _startingChangesetIndices?;
+    /** NOTE: the json properties must be converted to string before insertion */
+    private _targetScopeProvenanceProps;
+    private _cachedSynchronizationVersion;
+    private _targetClassNameToClassIdCache;
+    constructor(targetScopeElementId: Id64String, transformerOptions: IModelTransformOptions, syncTypeResolver: SyncTypeResolver);
+    private _isReverseSynchronization;
+    private _queryTargetRelId;
+    private _targetClassNameToClassId;
+    private _getRelClassId;
+    /** The element classes that are considered to define provenance in the iModel */
+    static get provenanceElementClasses(): (typeof Entity)[];
+    /** The element aspect classes that are considered to define provenance in the iModel */
+    static get provenanceElementAspectClasses(): (typeof Entity)[];
+    /**
+     * Iterate all matching federation guids and ExternalSourceAspects in the provenance iModel (target unless reverse sync)
+     * and call a function for each one.
+     * @note provenance is done by federation guids where possible
+     * @note this may execute on each element more than once! Only use in cases where that is handled
+     */
+    static forEachTrackedElement(args: {
+        provenanceSourceDb: IModelDb;
+        provenanceDb: IModelDb;
+        targetScopeElementId: Id64String;
+        isReverseSynchronization: boolean;
+        fn: (sourceElementId: Id64String, targetElementId: Id64String) => void;
+        skipPropagateChangesToRootElements: boolean;
+    }): Promise<void>;
+    /**
+     * Queries for an ESA which matches the props in the provided aspectProps.
+     * @param dbToQuery db to run the query on
+     * @param aspectProps aspectProps to search for
+     */
+    static queryScopeExternalSourceAspect(dbToQuery: IModelDb, aspectProps: ExternalSourceAspectProps): Promise<{
+        aspectId: Id64String;
+        version?: string;
+        /** stringified json */
+        jsonProperties?: string;
+    } | undefined>;
+    /** Return the IModelDb where provenance is stored.
+     * This will be targetDb except when it is a reverse synchronization, in which case it will be sourceDb.
+     */
+    private getProvenanceDb;
+    /** Return the IModelDb where entities referred to by stored provenance live.
+     * This will be sourceDb except when it is a reverse synchronization, in which case it will be targetDb.
+     */
+    getProvenanceSourceDb(): Promise<IModelDb>;
+    /**
+     * @returns provenance scope aspect if it exists in the provenanceDb.
+     * Provenance scope aspect is created and inserted into provenanceDb when [[initScopeProvenance]] is invoked.
+     */
+    tryGetProvenanceScopeAspect(): Promise<ExternalSourceAspect | undefined>;
+    /**
+     * Make sure there are no conflicting other scope-type external source aspects on the target scope element.
+     * If there are none at all, insert one (this must be a first synchronization).
+     */
+    initScopeProvenance(): Promise<void>;
+    /** Returns true if a change was made to the aspectProps. */
+    private handleUnsafeMigrate;
+    /**
+     * We cache the synchronization version to avoid querying the target scoping ESA multiple times.
+     * Clears the cached value so the next call to getSynchronizationVersion re-queries.
+     */
+    clearCachedSynchronizationVersion(): void;
+    /** The changeset version in the scoping element's source version found for this transformation.
+     * @note the version depends on whether this is a reverse synchronization or not.
+     * @note empty string and -1 for changeset and index if it has never been transformed.
+     */
+    getSynchronizationVersion(): Promise<ChangesetIndexAndId>;
+    /**
+     * Returns the pending changeset indices to skip for the current synchronization direction.
+     * Used by changeset initialization to determine which changesets have already been processed.
+     */
+    getChangesetsToSkip(): Promise<number[]>;
+    /**
+     * Updates the synchronization version on the scope ESA.
+     *
+     * Called at the end of a transformation, updates the target scope element to record
+     * that transformation up through the source's changeset has been performed. Also stores
+     * all changesets that occurred during the transformation as "pending synchronization
+     * changeset indices" @see TargetScopeProvenanceJsonProps
+     *
+     * @param initializeReverseSyncVersion When true, saves the reverse sync version as the
+     * current changeset of the targetDb. This is typically used for the first transformation
+     * between a master and branch iModel. Setting this to true has the effect of making it so
+     * any changesets in the branch iModel at the time of the first transformation will be
+     * ignored during any future reverse synchronizations from the branch to the master iModel.
+     *
+     * Note that typically, the reverseSyncVersion is saved as the last changeset merged from
+     * the branch into master. Setting initializeReverseSyncVersion to true during a forward
+     * transformation could overwrite this correct reverseSyncVersion and should only be done
+     * during the first transformation between a master and branch iModel.
+     *
+     * @param sourceChangeDataState The current state of change data — used to skip updates
+     * when there are no changes.
+     */
+    updateSynchronizationVersion({ initializeReverseSyncVersion, sourceChangeDataState, }: {
+        initializeReverseSyncVersion?: boolean;
+        sourceChangeDataState: "uninited" | "has-changes" | "no-changes" | "unconnected";
+    }): Promise<void>;
+    /** Create ExternalSourceAspectProps for an element in an iModel → iModel transformation. */
+    static initElementProvenanceOptions(sourceElementId: Id64String, targetElementId: Id64String, args: {
+        sourceDb: IModelDb;
+        targetDb: IModelDb;
+        isReverseSynchronization: boolean;
+        targetScopeElementId: Id64String;
+    }): ExternalSourceAspectProps;
+    /** Create ExternalSourceAspectProps for a relationship in an iModel → iModel transformation. */
+    static initRelationshipProvenanceOptions(sourceRelInstanceId: Id64String, targetRelInstanceId: Id64String, args: {
+        sourceDb: IModelDb;
+        targetDb: IModelDb;
+        isReverseSynchronization: boolean;
+        targetScopeElementId: Id64String;
+        forceOldRelationshipProvenanceMethod: boolean;
+    }): Promise<ExternalSourceAspectProps>;
+    /** Create an ExternalSourceAspectProps for an element using this manager's context. */
+    initElementProvenance(sourceElementId: Id64String, targetElementId: Id64String): Promise<ExternalSourceAspectProps>;
+    /** Create an ExternalSourceAspectProps for a relationship using this manager's context. */
+    initRelationshipProvenance(sourceRelInstanceId: Id64String, targetRelInstanceId: Id64String, forceOldRelationshipProvenanceMethod: boolean): Promise<ExternalSourceAspectProps>;
+    /**
+     * Queries the provenanceDb for an ESA whose identifier matches the provided element ID.
+     * @param entityInProvenanceSourceId ID of the element in the provenanceSourceDb
+     */
+    queryProvenanceForElement(entityInProvenanceSourceId: Id64String): Promise<Id64String | undefined>;
+    /**
+     * Queries the provenanceDb for an ESA whose identifier matches the provided relationship ID.
+     * @param entityInProvenanceSourceId ID of the relationship in the provenanceSourceDb
+     * @param sourceRelInfo Source relationship class and endpoint info (for legacy fallback)
+     */
+    queryProvenanceForRelationship(entityInProvenanceSourceId: Id64String, sourceRelInfo: {
+        classFullName: string;
+        sourceId: Id64String;
+        targetId: Id64String;
+    }): Promise<{
+        aspectId: Id64String;
+        /** if undefined, the relationship could not be found, perhaps it was deleted */
+        relationshipId: Id64String | undefined;
+    } | undefined>;
+    /** Instance convenience that calls the static forEachTrackedElement with this manager's context. */
+    forEachTrackedElement(fn: (sourceElementId: Id64String, targetElementId: Id64String) => void): Promise<void>;
+}
+//# sourceMappingURL=ProvenanceManager.d.ts.map

package/lib/cjs/ProvenanceManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProvenanceManager.d.ts","sourceRoot":"","sources":["../../src/ProvenanceManager.ts"],"names":[],"mappings":"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"}