@itwin/imodel-transformer 2.0.0-dev.9 → 2.0.0-experimental.0

package/lib/cjs/ElementAspectCleanup.js

@@ -0,0 +1,175 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ElementAspectCleanup = void 0;
+exports.isSameClass = isSameClass;
+exports.tryGetAspect = tryGetAspect;
+const core_backend_1 = require("@itwin/core-backend");
+const core_bentley_1 = require("@itwin/core-bentley");
+const core_common_1 = require("@itwin/core-common");
+/** Deletes replaceable ElementAspects of target owners that an owner batch did not reuse, while preserving excluded classes and aspects the caller protects, such as transformer provenance.
+ *
+ * Usage per owner batch: [[collect]] the aspects the owners have before import, let the importer [[retain]] each aspect it reuses or deletes itself, then [[deleteUnretained]] to delete the rest, or [[discard]] the batch if its export failed.
+ * While a batch is active, [[getAspects]] answers target aspect reads for its owners from the aspects loaded by [[collect]], so the importer doesn't query each owner separately.
+ * The importer brackets its own aspect writes with [[beforeWrite]] and [[afterWrite]]. If anything else writes to the target during the batch, including direct `EditTxn` calls, the loaded aspects are dropped and reads go to the target for the rest of the batch.
+ * @internal
+ */
+class ElementAspectCleanup {
+    _targetDb;
+    _editTxn;
+    _deleteAspect;
+    /** IDs of the batch owners' replaceable target aspects that the importer has not yet reused or deleted. [[collect]] fills it, [[retain]] removes from it, and [[deleteUnretained]] deletes what is left. */
+    _candidateIds = new Set();
+    /** Every target aspect of each batch owner that has not been written since [[collect]], keyed by owner. */
+    _aspectsByOwner = new Map();
+    /** The target connection's change count after [[collect]] or the importer's last write; undefined when no aspects are loaded. */
+    _expectedChangeCount;
+    constructor(_targetDb, _editTxn, _deleteAspect) {
+        this._targetDb = _targetDb;
+        this._editTxn = _editTxn;
+        this._deleteAspect = _deleteAspect;
+    }
+    /** Records the replaceable unique and multi-aspects owned by the supplied target elements as deletion candidates, replacing any previous candidates.
+     * Aspects of excluded classes, and aspects for which `isProtected` returns true, are never candidates.
+     */
+    async collect(targetElementIds, excludedElementAspectClassFullNames, isProtected = () => false) {
+        // Build the batch locally so a failed query leaves no partial batch behind.
+        this.discard();
+        if (targetElementIds.size === 0)
+            return;
+        const candidateIds = new Set();
+        const aspectsByOwner = new Map();
+        const targetExcludedElementAspectClassFullNames = [
+            ...excludedElementAspectClassFullNames,
+        ].filter((classFullName) => this._targetDb.containsClass(classFullName));
+        for (const aspectClassFullName of [
+            core_backend_1.ElementUniqueAspect.classFullName,
+            core_backend_1.ElementMultiAspect.classFullName,
+        ]) {
+            const { ecsql, params } = replaceableAspectQuery(aspectClassFullName, targetElementIds, targetExcludedElementAspectClassFullNames);
+            for await (const row of this._targetDb.createQueryReader(ecsql, params, {
+                usePrimaryConn: true,
+            })) {
+                candidateIds.add(row.id);
+            }
+        }
+        // Load every aspect, including excluded classes and protected aspects, so
+        // reads answer exactly what getAspects would for these owners.
+        for (const elementId of targetElementIds)
+            aspectsByOwner.set(elementId, []);
+        for await (const aspect of this._targetDb.elements.queryAspects({
+            elementIds: [...targetElementIds],
+            groupByOwner: true,
+            usePrimaryConn: true,
+        })) {
+            aspectsByOwner.get(aspect.element.id)?.push(aspect);
+            if (isProtected(aspect))
+                candidateIds.delete(aspect.id);
+        }
+        this._candidateIds = candidateIds;
+        this._aspectsByOwner = aspectsByOwner;
+        this._expectedChangeCount = this.targetChangeCount();
+    }
+    /** Returns the owner's target aspects of exactly `classFullName`, or all of them when it is omitted, in ECInstanceId order, from the aspects loaded by [[collect]].
+     * Returns undefined when the owner is not in the active batch or has been written since [[collect]]; the caller must then read the target.
+     */
+    getAspects(elementId, classFullName) {
+        this.dropLoadedAspectsIfChangedElsewhere();
+        const aspects = this._aspectsByOwner.get(elementId);
+        if (classFullName === undefined)
+            return aspects;
+        return aspects?.filter((aspect) => isSameClass(aspect, classFullName));
+    }
+    /** Call right before the importer writes an aspect of `elementId`. Later reads for that owner go to the target. */
+    beforeWrite(elementId) {
+        this.dropLoadedAspectsIfChangedElsewhere();
+        this._aspectsByOwner.delete(elementId);
+    }
+    /** Call right after the importer's write so that it isn't mistaken for a write made elsewhere. */
+    afterWrite() {
+        if (this._expectedChangeCount !== undefined)
+            this._expectedChangeCount = this.targetChangeCount();
+    }
+    /** Discards the batch without deleting anything. */
+    discard() {
+        this._candidateIds = new Set();
+        this._aspectsByOwner = new Map();
+        this._expectedChangeCount = undefined;
+    }
+    /** Drops all loaded aspects if the target changed since [[collect]] or the importer's last write, which means code other than the importer wrote to it. */
+    dropLoadedAspectsIfChangedElsewhere() {
+        if (this._expectedChangeCount === undefined ||
+            this.targetChangeCount() === this._expectedChangeCount)
+            return;
+        this._aspectsByOwner = new Map();
+        this._expectedChangeCount = undefined;
+    }
+    /** SQLite's count of rows inserted, updated, or deleted on the target connection since it opened. Reads don't change it. */
+    targetChangeCount() {
+        return this._targetDb.withPreparedSqliteStatement("SELECT total_changes()", (statement) => {
+            statement.step();
+            return statement.getValue(0).getInteger();
+        });
+    }
+    /** Removes an aspect from the deletion candidates because the importer reused or already deleted it. */
+    retain(aspectId) {
+        this._candidateIds.delete(aspectId);
+    }
+    /** Deletes the remaining candidates through the configured callback and clears them.
+     * Requires the target `EditTxn` to be active when there is anything to delete.
+     */
+    async deleteUnretained() {
+        const candidateIds = this._candidateIds;
+        this.discard();
+        if (candidateIds.size === 0)
+            return;
+        if (!this._editTxn.isActive) {
+            throw new Error("The target EditTxn must be active when deleting ElementAspects.");
+        }
+        for (const aspectId of candidateIds) {
+            // Deleting a unique aspect also deletes unique aspects of derived
+            // classes on the same element, so a candidate may already be gone.
+            const aspect = tryGetAspect(this._targetDb, aspectId);
+            if (aspect !== undefined)
+                await this._deleteAspect(aspect);
+        }
+    }
+}
+exports.ElementAspectCleanup = ElementAspectCleanup;
+/** Builds the query for aspects of `aspectClassFullName` owned by `elementIds`, skipping excluded classes. */
+function replaceableAspectQuery(aspectClassFullName, elementIds, excludedClassFullNames) {
+    const params = new core_common_1.QueryBinder().bindIdSet("elementIds", elementIds);
+    const whereClause = excludedClassFullNames.length > 0
+        ? `WHERE aspect.ECClassId IS NOT (${excludedClassFullNames.join(", ")})`
+        : "";
+    const ecsql = `SELECT aspect.ECInstanceId as id
+    FROM ${aspectClassFullName} aspect
+    INNER JOIN IdSet(:elementIds) ids ON ids.id = aspect.Element.Id
+    ${whereClause}`;
+    return { ecsql, params };
+}
+/** Whether an aspect is exactly of class `classFullName`, which may use either `:` or `.` as the separator.
+ * @internal
+ */
+function isSameClass(aspect, classFullName) {
+    return (aspect.classFullName.toLowerCase() ===
+        classFullName.replace(".", ":").toLowerCase());
+}
+/** Returns the aspect, or undefined if it no longer exists.
+ * @internal
+ */
+function tryGetAspect(db, aspectId) {
+    try {
+        return db.elements.getAspect(aspectId);
+    }
+    catch (error) {
+        if (error instanceof core_common_1.IModelError &&
+            error.errorNumber === core_bentley_1.IModelStatus.NotFound)
+            return undefined;
+        throw error;
+    }
+}
+//# sourceMappingURL=ElementAspectCleanup.js.map

package/lib/cjs/ElementAspectCleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ElementAspectCleanup.js","sourceRoot":"","sources":["../../src/ElementAspectCleanup.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\n * Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n * See LICENSE.md in the project root for license terms and full copyright notice.\n *--------------------------------------------------------------------------------------------*/\n\nimport {\n  EditTxn,\n  ElementAspect,\n  ElementMultiAspect,\n  ElementUniqueAspect,\n  IModelDb,\n} from \"@itwin/core-backend\";\nimport { Id64String, IModelStatus } from \"@itwin/core-bentley\";\nimport { IModelError, QueryBinder } from \"@itwin/core-common\";\n\n/** Deletes replaceable ElementAspects of target owners that an owner batch did not reuse, while preserving excluded classes and aspects the caller protects, such as transformer provenance.\n *\n * Usage per owner batch: [[collect]] the aspects the owners have before import, let the importer [[retain]] each aspect it reuses or deletes itself, then [[deleteUnretained]] to delete the rest, or [[discard]] the batch if its export failed.\n * While a batch is active, [[getAspects]] answers target aspect reads for its owners from the aspects loaded by [[collect]], so the importer doesn't query each owner separately.\n * The importer brackets its own aspect writes with [[beforeWrite]] and [[afterWrite]]. If anything else writes to the target during the batch, including direct `EditTxn` calls, the loaded aspects are dropped and reads go to the target for the rest of the batch.\n * @internal\n */\nexport class ElementAspectCleanup {\n  /** IDs of the batch owners' replaceable target aspects that the importer has not yet reused or deleted. [[collect]] fills it, [[retain]] removes from it, and [[deleteUnretained]] deletes what is left. */\n  private _candidateIds = new Set<Id64String>();\n  /** Every target aspect of each batch owner that has not been written since [[collect]], keyed by owner. */\n  private _aspectsByOwner = new Map<Id64String, ElementAspect[]>();\n  /** The target connection's change count after [[collect]] or the importer's last write; undefined when no aspects are loaded. */\n  private _expectedChangeCount?: number;\n\n  public constructor(\n    private readonly _targetDb: IModelDb,\n    private readonly _editTxn: EditTxn,\n    private readonly _deleteAspect: (aspect: ElementAspect) => Promise<void>\n  ) {}\n\n  /** Records the replaceable unique and multi-aspects owned by the supplied target elements as deletion candidates, replacing any previous candidates.\n   * Aspects of excluded classes, and aspects for which `isProtected` returns true, are never candidates.\n   */\n  public async collect(\n    targetElementIds: ReadonlySet<Id64String>,\n    excludedElementAspectClassFullNames: ReadonlySet<string>,\n    isProtected: (aspect: ElementAspect) => boolean = () => false\n  ): Promise<void> {\n    // Build the batch locally so a failed query leaves no partial batch behind.\n    this.discard();\n    if (targetElementIds.size === 0) return;\n\n    const candidateIds = new Set<Id64String>();\n    const aspectsByOwner = new Map<Id64String, ElementAspect[]>();\n\n    const targetExcludedElementAspectClassFullNames = [\n      ...excludedElementAspectClassFullNames,\n    ].filter((classFullName) => this._targetDb.containsClass(classFullName));\n    for (const aspectClassFullName of [\n      ElementUniqueAspect.classFullName,\n      ElementMultiAspect.classFullName,\n    ]) {\n      const { ecsql, params } = replaceableAspectQuery(\n        aspectClassFullName,\n        targetElementIds,\n        targetExcludedElementAspectClassFullNames\n      );\n      for await (const row of this._targetDb.createQueryReader(ecsql, params, {\n        usePrimaryConn: true,\n      })) {\n        candidateIds.add(row.id);\n      }\n    }\n\n    // Load every aspect, including excluded classes and protected aspects, so\n    // reads answer exactly what getAspects would for these owners.\n    for (const elementId of targetElementIds) aspectsByOwner.set(elementId, []);\n    for await (const aspect of this._targetDb.elements.queryAspects({\n      elementIds: [...targetElementIds],\n      groupByOwner: true,\n      usePrimaryConn: true,\n    })) {\n      aspectsByOwner.get(aspect.element.id)?.push(aspect);\n      if (isProtected(aspect)) candidateIds.delete(aspect.id);\n    }\n\n    this._candidateIds = candidateIds;\n    this._aspectsByOwner = aspectsByOwner;\n    this._expectedChangeCount = this.targetChangeCount();\n  }\n\n  /** Returns the owner's target aspects of exactly `classFullName`, or all of them when it is omitted, in ECInstanceId order, from the aspects loaded by [[collect]].\n   * Returns undefined when the owner is not in the active batch or has been written since [[collect]]; the caller must then read the target.\n   */\n  public getAspects(\n    elementId: Id64String,\n    classFullName?: string\n  ): ElementAspect[] | undefined {\n    this.dropLoadedAspectsIfChangedElsewhere();\n    const aspects = this._aspectsByOwner.get(elementId);\n    if (classFullName === undefined) return aspects;\n    return aspects?.filter((aspect) => isSameClass(aspect, classFullName));\n  }\n\n  /** Call right before the importer writes an aspect of `elementId`. Later reads for that owner go to the target. */\n  public beforeWrite(elementId: Id64String): void {\n    this.dropLoadedAspectsIfChangedElsewhere();\n    this._aspectsByOwner.delete(elementId);\n  }\n\n  /** Call right after the importer's write so that it isn't mistaken for a write made elsewhere. */\n  public afterWrite(): void {\n    if (this._expectedChangeCount !== undefined)\n      this._expectedChangeCount = this.targetChangeCount();\n  }\n\n  /** Discards the batch without deleting anything. */\n  public discard(): void {\n    this._candidateIds = new Set<Id64String>();\n    this._aspectsByOwner = new Map<Id64String, ElementAspect[]>();\n    this._expectedChangeCount = undefined;\n  }\n\n  /** Drops all loaded aspects if the target changed since [[collect]] or the importer's last write, which means code other than the importer wrote to it. */\n  private dropLoadedAspectsIfChangedElsewhere(): void {\n    if (\n      this._expectedChangeCount === undefined ||\n      this.targetChangeCount() === this._expectedChangeCount\n    )\n      return;\n    this._aspectsByOwner = new Map<Id64String, ElementAspect[]>();\n    this._expectedChangeCount = undefined;\n  }\n\n  /** SQLite's count of rows inserted, updated, or deleted on the target connection since it opened. Reads don't change it. */\n  private targetChangeCount(): number {\n    return this._targetDb.withPreparedSqliteStatement(\n      \"SELECT total_changes()\",\n      (statement) => {\n        statement.step();\n        return statement.getValue(0).getInteger();\n      }\n    );\n  }\n\n  /** Removes an aspect from the deletion candidates because the importer reused or already deleted it. */\n  public retain(aspectId: Id64String): void {\n    this._candidateIds.delete(aspectId);\n  }\n\n  /** Deletes the remaining candidates through the configured callback and clears them.\n   * Requires the target `EditTxn` to be active when there is anything to delete.\n   */\n  public async deleteUnretained(): Promise<void> {\n    const candidateIds = this._candidateIds;\n    this.discard();\n    if (candidateIds.size === 0) return;\n\n    if (!this._editTxn.isActive) {\n      throw new Error(\n        \"The target EditTxn must be active when deleting ElementAspects.\"\n      );\n    }\n    for (const aspectId of candidateIds) {\n      // Deleting a unique aspect also deletes unique aspects of derived\n      // classes on the same element, so a candidate may already be gone.\n      const aspect = tryGetAspect(this._targetDb, aspectId);\n      if (aspect !== undefined) await this._deleteAspect(aspect);\n    }\n  }\n}\n\n/** Builds the query for aspects of `aspectClassFullName` owned by `elementIds`, skipping excluded classes. */\nfunction replaceableAspectQuery(\n  aspectClassFullName: string,\n  elementIds: ReadonlySet<Id64String>,\n  excludedClassFullNames: readonly string[]\n): { ecsql: string; params: QueryBinder } {\n  const params = new QueryBinder().bindIdSet(\"elementIds\", elementIds);\n  const whereClause =\n    excludedClassFullNames.length > 0\n      ? `WHERE aspect.ECClassId IS NOT (${excludedClassFullNames.join(\", \")})`\n      : \"\";\n  const ecsql = `SELECT aspect.ECInstanceId as id\n    FROM ${aspectClassFullName} aspect\n    INNER JOIN IdSet(:elementIds) ids ON ids.id = aspect.Element.Id\n    ${whereClause}`;\n  return { ecsql, params };\n}\n\n/** Whether an aspect is exactly of class `classFullName`, which may use either `:` or `.` as the separator.\n * @internal\n */\nexport function isSameClass(\n  aspect: { readonly classFullName: string },\n  classFullName: string\n): boolean {\n  return (\n    aspect.classFullName.toLowerCase() ===\n    classFullName.replace(\".\", \":\").toLowerCase()\n  );\n}\n\n/** Returns the aspect, or undefined if it no longer exists.\n * @internal\n */\nexport function tryGetAspect(\n  db: IModelDb,\n  aspectId: Id64String\n): ElementAspect | undefined {\n  try {\n    return db.elements.getAspect(aspectId);\n  } catch (error) {\n    if (\n      error instanceof IModelError &&\n      error.errorNumber === IModelStatus.NotFound\n    )\n      return undefined;\n    throw error;\n  }\n}\n"]}

package/lib/cjs/ElementAspectExportCoordinator.d.ts

@@ -0,0 +1,47 @@
+import { Id64String } from "@itwin/core-bentley";
+/** Completes an owner group. `exported` is false when exporting the group's aspects failed; the callback must then discard its state without throwing. */
+export type ElementAspectExportCompletion = (exported: boolean) => Promise<void>;
+/** Prepares an owner group before its aspects are exported. It may return a completion callback that runs after the group's aspects are exported, or after the export fails. */
+export type ElementAspectExportPreparation = (excludedElementAspectClassFullNames: ReadonlySet<string>, ownerElementIds: ReadonlySet<Id64String>) => Promise<ElementAspectExportCompletion | void>;
+/** Coordinates scoped batches of accepted ElementAspect owners, including preparation before aspect export.
+ * @internal
+ */
+export declare class ElementAspectExportCoordinator {
+    private readonly _defaultBatchSize;
+    private readonly _excludedClassFullNames;
+    private readonly _exportAspects;
+    private readonly _resetCaches;
+    private readonly _acceptedOwnerIds;
+    private readonly _processedOwnerIds;
+    private _batchSize;
+    private _depth;
+    private _prepare?;
+    constructor(_defaultBatchSize: number, _excludedClassFullNames: () => ReadonlySet<string>, _exportAspects: (ownerElementIds: ReadonlySet<Id64String>) => Promise<void>, _resetCaches?: () => void);
+    /** Whether an accepted-owner collection scope is active. */
+    get isActive(): boolean;
+    /** Sets the callback that prepares each accepted-owner group before its aspects are exported and optionally completes it afterward. */
+    setPreparation(prepare: ElementAspectExportPreparation): void;
+    /** Begins an accepted-owner collection scope.
+     * Nested scopes share the outer scope's state and batch size.
+     */
+    begin(batchSize?: number): void;
+    /** Ends an accepted-owner collection scope.
+     * Ending the outermost scope exports pending owners and resets all scope state.
+     */
+    end(): Promise<void>;
+    /** Discards the active scope and its pending owner state without exporting it. */
+    abort(): void;
+    /** Runs element export within an accepted-owner collection scope.
+     * A scope created by this call is aborted if element export fails; an existing outer scope remains responsible for its own failure handling.
+     */
+    run(exportElements: () => Promise<void>): Promise<void>;
+    /** Adds an accepted source owner to the current group and exports the group when it reaches the configured batch size. */
+    addAcceptedOwner(elementId: Id64String): Promise<void>;
+    /** Runs preparation and aspect export for an explicit owner set in bounded groups. */
+    exportOwners(ownerElementIds: ReadonlySet<Id64String>): Promise<void>;
+    private exportOwnerBatch;
+    private flush;
+    private resetScopeState;
+    private reset;
+}
+//# sourceMappingURL=ElementAspectExportCoordinator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ElementAspectExportCoordinator.d.ts","sourceRoot":"","sources":["../../src/ElementAspectExportCoordinator.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD,0JAA0J;AAC1J,MAAM,MAAM,6BAA6B,GAAG,CAC1C,QAAQ,EAAE,OAAO,KACd,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,gLAAgL;AAChL,MAAM,MAAM,8BAA8B,GAAG,CAC3C,mCAAmC,EAAE,WAAW,CAAC,MAAM,CAAC,EACxD,eAAe,EAAE,WAAW,CAAC,UAAU,CAAC,KACrC,OAAO,CAAC,6BAA6B,GAAG,IAAI,CAAC,CAAC;AAEnD;;GAEG;AACH,qBAAa,8BAA8B;IAQvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAClC,OAAO,CAAC,QAAQ,CAAC,uBAAuB;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc;IAG/B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAZ/B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAyB;IAC3D,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAyB;IAC5D,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,CAAiC;IAElD,YACmB,iBAAiB,EAAE,MAAM,EACzB,uBAAuB,EAAE,MAAM,WAAW,CAAC,MAAM,CAAC,EAClD,cAAc,EAAE,CAC/B,eAAe,EAAE,WAAW,CAAC,UAAU,CAAC,KACrC,OAAO,CAAC,IAAI,CAAC,EACD,YAAY,GAAE,MAAM,IAAe,EAGrD;IAED,4DAA4D;IAC5D,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAED,uIAAuI;IAChI,cAAc,CAAC,OAAO,EAAE,8BAA8B,GAAG,IAAI,CAEnE;IAED;;OAEG;IACI,KAAK,CAAC,SAAS,SAAyB,GAAG,IAAI,CAOrD;IAED;;OAEG;IACU,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAehC;IAED,kFAAkF;IAC3E,KAAK,IAAI,IAAI,CAEnB;IAED;;OAEG;IACU,GAAG,CAAC,cAAc,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAcnE;IAED,0HAA0H;IAC7G,gBAAgB,CAAC,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAOlE;IAED,sFAAsF;IACzE,YAAY,CACvB,eAAe,EAAE,WAAW,CAAC,UAAU,CAAC,GACvC,OAAO,CAAC,IAAI,CAAC,CA8Bf;YAEa,gBAAgB;YAoBhB,KAAK;IAMnB,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,KAAK;CAKd"}

package/lib/cjs/ElementAspectExportCoordinator.js

@@ -0,0 +1,160 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ElementAspectExportCoordinator = void 0;
+/** Coordinates scoped batches of accepted ElementAspect owners, including preparation before aspect export.
+ * @internal
+ */
+class ElementAspectExportCoordinator {
+    _defaultBatchSize;
+    _excludedClassFullNames;
+    _exportAspects;
+    _resetCaches;
+    _acceptedOwnerIds = new Set();
+    _processedOwnerIds = new Set();
+    _batchSize;
+    _depth = 0;
+    _prepare;
+    constructor(_defaultBatchSize, _excludedClassFullNames, _exportAspects, _resetCaches = () => { }) {
+        this._defaultBatchSize = _defaultBatchSize;
+        this._excludedClassFullNames = _excludedClassFullNames;
+        this._exportAspects = _exportAspects;
+        this._resetCaches = _resetCaches;
+        this._batchSize = _defaultBatchSize;
+    }
+    /** Whether an accepted-owner collection scope is active. */
+    get isActive() {
+        return this._depth > 0;
+    }
+    /** Sets the callback that prepares each accepted-owner group before its aspects are exported and optionally completes it afterward. */
+    setPreparation(prepare) {
+        this._prepare = prepare;
+    }
+    /** Begins an accepted-owner collection scope.
+     * Nested scopes share the outer scope's state and batch size.
+     */
+    begin(batchSize = this._defaultBatchSize) {
+        if (this._depth === 0) {
+            this.resetScopeState();
+            this._resetCaches();
+            this._batchSize = batchSize;
+        }
+        this._depth++;
+    }
+    /** Ends an accepted-owner collection scope.
+     * Ending the outermost scope exports pending owners and resets all scope state.
+     */
+    async end() {
+        if (this._depth === 0) {
+            throw new Error("No scoped element export is active.");
+        }
+        this._depth--;
+        if (this._depth > 0)
+            return;
+        try {
+            if (this._acceptedOwnerIds.size > 0) {
+                await this.flush();
+            }
+        }
+        finally {
+            this.reset();
+        }
+    }
+    /** Discards the active scope and its pending owner state without exporting it. */
+    abort() {
+        this.reset();
+    }
+    /** Runs element export within an accepted-owner collection scope.
+     * A scope created by this call is aborted if element export fails; an existing outer scope remains responsible for its own failure handling.
+     */
+    async run(exportElements) {
+        if (this.isActive) {
+            await exportElements();
+            return;
+        }
+        this.begin();
+        try {
+            await exportElements();
+        }
+        catch (error) {
+            this.abort();
+            throw error;
+        }
+        await this.end();
+    }
+    /** Adds an accepted source owner to the current group and exports the group when it reaches the configured batch size. */
+    async addAcceptedOwner(elementId) {
+        if (!this.isActive || this._processedOwnerIds.has(elementId))
+            return;
+        this._acceptedOwnerIds.add(elementId);
+        if (this._acceptedOwnerIds.size >= this._batchSize) {
+            await this.flush();
+        }
+    }
+    /** Runs preparation and aspect export for an explicit owner set in bounded groups. */
+    async exportOwners(ownerElementIds) {
+        let ownerIds = ownerElementIds;
+        if (this.isActive && ownerElementIds.size > 0) {
+            const unprocessedOwnerIds = new Set();
+            for (const elementId of ownerElementIds) {
+                if (!this._processedOwnerIds.has(elementId)) {
+                    unprocessedOwnerIds.add(elementId);
+                    this._processedOwnerIds.add(elementId);
+                }
+            }
+            if (unprocessedOwnerIds.size === 0)
+                return;
+            ownerIds = unprocessedOwnerIds;
+        }
+        if (ownerIds.size <= this._defaultBatchSize) {
+            await this.exportOwnerBatch(ownerIds);
+            return;
+        }
+        let ownerBatch = new Set();
+        for (const elementId of ownerIds) {
+            ownerBatch.add(elementId);
+            if (ownerBatch.size === this._defaultBatchSize) {
+                await this.exportOwnerBatch(ownerBatch);
+                ownerBatch = new Set();
+            }
+        }
+        if (ownerBatch.size > 0) {
+            await this.exportOwnerBatch(ownerBatch);
+        }
+    }
+    async exportOwnerBatch(ownerElementIds) {
+        const complete = await this._prepare?.(this._excludedClassFullNames(), ownerElementIds);
+        try {
+            await this._exportAspects(ownerElementIds);
+        }
+        catch (error) {
+            try {
+                await complete?.(false);
+            }
+            catch {
+                // Keep the export error; it explains why the group failed.
+            }
+            throw error;
+        }
+        await complete?.(true);
+    }
+    async flush() {
+        const ownerElementIds = new Set(this._acceptedOwnerIds);
+        this._acceptedOwnerIds.clear();
+        await this.exportOwners(ownerElementIds);
+    }
+    resetScopeState() {
+        this._acceptedOwnerIds.clear();
+        this._processedOwnerIds.clear();
+    }
+    reset() {
+        this._depth = 0;
+        this.resetScopeState();
+        this._batchSize = this._defaultBatchSize;
+    }
+}
+exports.ElementAspectExportCoordinator = ElementAspectExportCoordinator;
+//# sourceMappingURL=ElementAspectExportCoordinator.js.map

package/lib/cjs/ElementAspectExportCoordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ElementAspectExportCoordinator.js","sourceRoot":"","sources":["../../src/ElementAspectExportCoordinator.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\n * Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n * See LICENSE.md in the project root for license terms and full copyright notice.\n *--------------------------------------------------------------------------------------------*/\n\nimport { Id64String } from \"@itwin/core-bentley\";\n\n/** Completes an owner group. `exported` is false when exporting the group's aspects failed; the callback must then discard its state without throwing. */\nexport type ElementAspectExportCompletion = (\n  exported: boolean\n) => Promise<void>;\n\n/** Prepares an owner group before its aspects are exported. It may return a completion callback that runs after the group's aspects are exported, or after the export fails. */\nexport type ElementAspectExportPreparation = (\n  excludedElementAspectClassFullNames: ReadonlySet<string>,\n  ownerElementIds: ReadonlySet<Id64String>\n) => Promise<ElementAspectExportCompletion | void>;\n\n/** Coordinates scoped batches of accepted ElementAspect owners, including preparation before aspect export.\n * @internal\n */\nexport class ElementAspectExportCoordinator {\n  private readonly _acceptedOwnerIds = new Set<Id64String>();\n  private readonly _processedOwnerIds = new Set<Id64String>();\n  private _batchSize: number;\n  private _depth = 0;\n  private _prepare?: ElementAspectExportPreparation;\n\n  public constructor(\n    private readonly _defaultBatchSize: number,\n    private readonly _excludedClassFullNames: () => ReadonlySet<string>,\n    private readonly _exportAspects: (\n      ownerElementIds: ReadonlySet<Id64String>\n    ) => Promise<void>,\n    private readonly _resetCaches: () => void = () => {}\n  ) {\n    this._batchSize = _defaultBatchSize;\n  }\n\n  /** Whether an accepted-owner collection scope is active. */\n  public get isActive(): boolean {\n    return this._depth > 0;\n  }\n\n  /** Sets the callback that prepares each accepted-owner group before its aspects are exported and optionally completes it afterward. */\n  public setPreparation(prepare: ElementAspectExportPreparation): void {\n    this._prepare = prepare;\n  }\n\n  /** Begins an accepted-owner collection scope.\n   * Nested scopes share the outer scope's state and batch size.\n   */\n  public begin(batchSize = this._defaultBatchSize): void {\n    if (this._depth === 0) {\n      this.resetScopeState();\n      this._resetCaches();\n      this._batchSize = batchSize;\n    }\n    this._depth++;\n  }\n\n  /** Ends an accepted-owner collection scope.\n   * Ending the outermost scope exports pending owners and resets all scope state.\n   */\n  public async end(): Promise<void> {\n    if (this._depth === 0) {\n      throw new Error(\"No scoped element export is active.\");\n    }\n\n    this._depth--;\n    if (this._depth > 0) return;\n\n    try {\n      if (this._acceptedOwnerIds.size > 0) {\n        await this.flush();\n      }\n    } finally {\n      this.reset();\n    }\n  }\n\n  /** Discards the active scope and its pending owner state without exporting it. */\n  public abort(): void {\n    this.reset();\n  }\n\n  /** Runs element export within an accepted-owner collection scope.\n   * A scope created by this call is aborted if element export fails; an existing outer scope remains responsible for its own failure handling.\n   */\n  public async run(exportElements: () => Promise<void>): Promise<void> {\n    if (this.isActive) {\n      await exportElements();\n      return;\n    }\n\n    this.begin();\n    try {\n      await exportElements();\n    } catch (error) {\n      this.abort();\n      throw error;\n    }\n    await this.end();\n  }\n\n  /** Adds an accepted source owner to the current group and exports the group when it reaches the configured batch size. */\n  public async addAcceptedOwner(elementId: Id64String): Promise<void> {\n    if (!this.isActive || this._processedOwnerIds.has(elementId)) return;\n\n    this._acceptedOwnerIds.add(elementId);\n    if (this._acceptedOwnerIds.size >= this._batchSize) {\n      await this.flush();\n    }\n  }\n\n  /** Runs preparation and aspect export for an explicit owner set in bounded groups. */\n  public async exportOwners(\n    ownerElementIds: ReadonlySet<Id64String>\n  ): Promise<void> {\n    let ownerIds = ownerElementIds;\n    if (this.isActive && ownerElementIds.size > 0) {\n      const unprocessedOwnerIds = new Set<Id64String>();\n      for (const elementId of ownerElementIds) {\n        if (!this._processedOwnerIds.has(elementId)) {\n          unprocessedOwnerIds.add(elementId);\n          this._processedOwnerIds.add(elementId);\n        }\n      }\n      if (unprocessedOwnerIds.size === 0) return;\n      ownerIds = unprocessedOwnerIds;\n    }\n\n    if (ownerIds.size <= this._defaultBatchSize) {\n      await this.exportOwnerBatch(ownerIds);\n      return;\n    }\n\n    let ownerBatch = new Set<Id64String>();\n    for (const elementId of ownerIds) {\n      ownerBatch.add(elementId);\n      if (ownerBatch.size === this._defaultBatchSize) {\n        await this.exportOwnerBatch(ownerBatch);\n        ownerBatch = new Set<Id64String>();\n      }\n    }\n    if (ownerBatch.size > 0) {\n      await this.exportOwnerBatch(ownerBatch);\n    }\n  }\n\n  private async exportOwnerBatch(\n    ownerElementIds: ReadonlySet<Id64String>\n  ): Promise<void> {\n    const complete = await this._prepare?.(\n      this._excludedClassFullNames(),\n      ownerElementIds\n    );\n    try {\n      await this._exportAspects(ownerElementIds);\n    } catch (error) {\n      try {\n        await complete?.(false);\n      } catch {\n        // Keep the export error; it explains why the group failed.\n      }\n      throw error;\n    }\n    await complete?.(true);\n  }\n\n  private async flush(): Promise<void> {\n    const ownerElementIds = new Set(this._acceptedOwnerIds);\n    this._acceptedOwnerIds.clear();\n    await this.exportOwners(ownerElementIds);\n  }\n\n  private resetScopeState(): void {\n    this._acceptedOwnerIds.clear();\n    this._processedOwnerIds.clear();\n  }\n\n  private reset(): void {\n    this._depth = 0;\n    this.resetScopeState();\n    this._batchSize = this._defaultBatchSize;\n  }\n}\n"]}

package/lib/cjs/ElementAspectExportProcessor.d.ts

@@ -0,0 +1,44 @@
+import { ElementAspect, ElementMultiAspect, ElementUniqueAspect, IModelDb } from "@itwin/core-backend";
+import { Id64String } from "@itwin/core-bentley";
+interface AspectChanges {
+    readonly insertIds: ReadonlySet<Id64String>;
+    readonly updateIds: ReadonlySet<Id64String>;
+}
+export interface ElementAspectExportProcessorHandler {
+    shouldExportElementAspect(aspect: ElementAspect): Promise<boolean>;
+    onExportElementUniqueAspect(uniqueAspect: ElementUniqueAspect, isUpdate?: boolean | undefined): Promise<void>;
+    onExportElementMultiAspects(multiAspects: ElementMultiAspect[]): Promise<void>;
+    trackProgress: () => Promise<void>;
+}
+/** Queries and exports ElementAspects for accepted source owners, applying class and handler filters and grouping multi-aspects by owner.
+ * @internal
+ */
+export declare class ElementAspectExportProcessor {
+    /** ElementAspect classes excluded from source queries. */
+    private readonly _excludedElementAspectClassFullNames;
+    private _hasExportableAspects;
+    private _expandedExcludedElementAspectClassFullNames;
+    private _aspectChanges;
+    /** ElementAspect class names excluded from source queries. */
+    get excludedElementAspectClassFullNames(): ReadonlySet<string>;
+    private readonly _sourceDb;
+    private readonly _handler;
+    constructor(sourceDb: IModelDb, handler: ElementAspectExportProcessorHandler);
+    /** Exports ElementAspects owned by the supplied elements.
+     * Multi-aspects are emitted in one callback group per owner.
+     */
+    exportAllElementAspects(ownerElementIds: ReadonlySet<Id64String>): Promise<void>;
+    /** Sets the aspect changes used to distinguish inserted and updated unique aspects during change export. */
+    setAspectChanges(aspectChanges?: AspectChanges): void;
+    /** Clears source schema and content caches at an outer export-scope boundary. */
+    resetCaches(): void;
+    /** Excludes an ElementAspect class from subsequent queries and export callbacks. */
+    excludeElementAspectClass(classFullName: string): void;
+    private getExcludedClassFilter;
+    private getHasExportableAspects;
+    private queryHasExportableAspects;
+    private getExpandedExcludedElementAspectClassFullNames;
+    private queryExpandedExcludedElementAspectClassFullNames;
+}
+export {};
+//# sourceMappingURL=ElementAspectExportProcessor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ElementAspectExportProcessor.d.ts","sourceRoot":"","sources":["../../src/ElementAspectExportProcessor.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,QAAQ,EACT,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAIjD,UAAU,aAAa;IACrB,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,mCAAmC;IAClD,yBAAyB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE,2BAA2B,CACzB,YAAY,EAAE,mBAAmB,EACjC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,GAC7B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,2BAA2B,CACzB,YAAY,EAAE,kBAAkB,EAAE,GACjC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,qBAAa,4BAA4B;IACvC,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,oCAAoC,CAAqB;IAC1E,OAAO,CAAC,qBAAqB,CAA+B;IAC5D,OAAO,CAAC,4CAA4C,CAEtC;IACd,OAAO,CAAC,cAAc,CAA4B;IAElD,8DAA8D;IAC9D,IAAW,mCAAmC,IAAI,WAAW,CAAC,MAAM,CAAC,CAEpE;IACD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAE/D,YACE,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,mCAAmC,EAI7C;IAED;;OAEG;IACU,uBAAuB,CAClC,eAAe,EAAE,WAAW,CAAC,UAAU,CAAC,GACvC,OAAO,CAAC,IAAI,CAAC,CAkDf;IAED,4GAA4G;IACrG,gBAAgB,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,CAE3D;IAED,iFAAiF;IAC1E,WAAW,IAAI,IAAI,CAGzB;IAED,oFAAoF;IAC7E,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAM5D;IAED,OAAO,CAAC,sBAAsB;YAkBhB,uBAAuB;YAKvB,yBAAyB;YAuBzB,8CAA8C;YAQ9C,gDAAgD;CAmB/D"}

package/lib/cjs/ElementAspectExportProcessor.js

@@ -0,0 +1,152 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ElementAspectExportProcessor = void 0;
+const core_backend_1 = require("@itwin/core-backend");
+const ECSqlReaderAsyncIterableIteratorAdapter_1 = require("./ECSqlReaderAsyncIterableIteratorAdapter");
+const core_common_1 = require("@itwin/core-common");
+/** Queries and exports ElementAspects for accepted source owners, applying class and handler filters and grouping multi-aspects by owner.
+ * @internal
+ */
+class ElementAspectExportProcessor {
+    /** ElementAspect classes excluded from source queries. */
+    _excludedElementAspectClassFullNames = new Set();
+    _hasExportableAspects;
+    _expandedExcludedElementAspectClassFullNames;
+    _aspectChanges;
+    /** ElementAspect class names excluded from source queries. */
+    get excludedElementAspectClassFullNames() {
+        return this._excludedElementAspectClassFullNames;
+    }
+    _sourceDb;
+    _handler;
+    constructor(sourceDb, handler) {
+        this._sourceDb = sourceDb;
+        this._handler = handler;
+    }
+    /** Exports ElementAspects owned by the supplied elements.
+     * Multi-aspects are emitted in one callback group per owner.
+     */
+    async exportAllElementAspects(ownerElementIds) {
+        if (ownerElementIds.size === 0 || !(await this.getHasExportableAspects()))
+            return;
+        let multiAspectOwnerId;
+        let multiAspects = [];
+        const exportMultiAspects = async () => {
+            if (multiAspects.length === 0)
+                return;
+            await this._handler.onExportElementMultiAspects(multiAspects);
+            await this._handler.trackProgress();
+            multiAspects = [];
+            multiAspectOwnerId = undefined;
+        };
+        const excludedAspectClassFullNames = await this.getExpandedExcludedElementAspectClassFullNames();
+        for await (const aspect of this._sourceDb.elements.queryAspects({
+            elementIds: new Set(ownerElementIds),
+            excludedAspectClassFullNames,
+            groupByOwner: true,
+            usePrimaryConn: true,
+        })) {
+            if (!(await this._handler.shouldExportElementAspect(aspect)))
+                continue;
+            if (multiAspectOwnerId !== undefined &&
+                multiAspectOwnerId !== aspect.element.id) {
+                await exportMultiAspects();
+            }
+            if (aspect instanceof core_backend_1.ElementUniqueAspect) {
+                const isUpdate = this._aspectChanges?.updateIds.has(aspect.id)
+                    ? true
+                    : this._aspectChanges?.insertIds.has(aspect.id)
+                        ? false
+                        : undefined;
+                await this._handler.onExportElementUniqueAspect(aspect, isUpdate);
+                await this._handler.trackProgress();
+            }
+            else if (aspect instanceof core_backend_1.ElementMultiAspect) {
+                multiAspectOwnerId = aspect.element.id;
+                multiAspects.push(aspect);
+            }
+            else {
+                throw new Error(`Unexpected ElementAspect type ${aspect.classFullName}`);
+            }
+        }
+        await exportMultiAspects();
+    }
+    /** Sets the aspect changes used to distinguish inserted and updated unique aspects during change export. */
+    setAspectChanges(aspectChanges) {
+        this._aspectChanges = aspectChanges;
+    }
+    /** Clears source schema and content caches at an outer export-scope boundary. */
+    resetCaches() {
+        this._hasExportableAspects = undefined;
+        this._expandedExcludedElementAspectClassFullNames = undefined;
+    }
+    /** Excludes an ElementAspect class from subsequent queries and export callbacks. */
+    excludeElementAspectClass(classFullName) {
+        const normalizedClassFullName = classFullName.replace(".", ":");
+        if (this._excludedElementAspectClassFullNames.has(normalizedClassFullName))
+            return;
+        this._excludedElementAspectClassFullNames.add(normalizedClassFullName);
+        this.resetCaches();
+    }
+    getExcludedClassFilter(queryParams) {
+        const excludedClassParameters = [];
+        let excludedClassIndex = 0;
+        for (const classFullName of this._excludedElementAspectClassFullNames) {
+            const parameterName = `excludedAspectClass${excludedClassIndex++}`;
+            excludedClassParameters.push(`ec_classid(:${parameterName})`);
+            queryParams.bindString(parameterName, classFullName);
+        }
+        return excludedClassParameters.length === 0
+            ? ""
+            : `AND NOT EXISTS (
+          SELECT 1 FROM meta.ClassHasAllBaseClasses excluded
+          WHERE excluded.SourceECInstanceId = aspect.ECClassId
+            AND excluded.TargetECInstanceId IN (${excludedClassParameters.join(",")})
+        )`;
+    }
+    async getHasExportableAspects() {
+        this._hasExportableAspects ??= this.queryHasExportableAspects();
+        return this._hasExportableAspects;
+    }
+    async queryHasExportableAspects() {
+        const queryParams = new core_common_1.QueryBinder();
+        const excludedClassFilter = this.getExcludedClassFilter(queryParams);
+        const reader = this._sourceDb.createQueryReader(`SELECT ECInstanceId FROM (
+         SELECT aspect.ECInstanceId
+         FROM Bis.ElementMultiAspect aspect
+         WHERE TRUE ${excludedClassFilter}
+         UNION ALL
+         SELECT aspect.ECInstanceId
+         FROM Bis.ElementUniqueAspect aspect
+         WHERE TRUE ${excludedClassFilter}
+       )
+       LIMIT 1`, queryParams, { usePrimaryConn: true });
+        for await (const _row of (0, ECSqlReaderAsyncIterableIteratorAdapter_1.ensureECSqlReaderIsAsyncIterableIterator)(reader))
+            return true;
+        return false;
+    }
+    async getExpandedExcludedElementAspectClassFullNames() {
+        this._expandedExcludedElementAspectClassFullNames ??=
+            this.queryExpandedExcludedElementAspectClassFullNames();
+        return this._expandedExcludedElementAspectClassFullNames;
+    }
+    async queryExpandedExcludedElementAspectClassFullNames() {
+        const excludedClassFullNames = new Set();
+        for (const classFullName of this._excludedElementAspectClassFullNames) {
+            const reader = this._sourceDb.createQueryReader(`SELECT ec_classname(classes.ECInstanceId, 's:c') AS classFullName
+         FROM meta.ClassHasAllBaseClasses inheritance
+         JOIN meta.ECClassDef classes
+           ON classes.ECInstanceId = inheritance.SourceECInstanceId
+         WHERE inheritance.TargetECInstanceId = ec_classid(:excludedClassName)`, new core_common_1.QueryBinder().bindString("excludedClassName", classFullName), { usePrimaryConn: true });
+            for await (const row of (0, ECSqlReaderAsyncIterableIteratorAdapter_1.ensureECSqlReaderIsAsyncIterableIterator)(reader))
+                excludedClassFullNames.add(row.classFullName);
+        }
+        return excludedClassFullNames;
+    }
+}
+exports.ElementAspectExportProcessor = ElementAspectExportProcessor;
+//# sourceMappingURL=ElementAspectExportProcessor.js.map