@itwin/core-backend 5.15.0-dev.2 → 5.15.0-dev.20

package/lib/esm/EditTxn.d.ts

@@ -10,34 +10,62 @@ import type { ChangeElementModelProps, ChangeElementParentProps, IModelDb, Inser
 import type { SettingsContainer } from "./workspace/Settings";
 /** Options for bulk deleting elements from an iModelDb.
  * @beta
+ * @deprecated Options are no longer used and [[EditTxn.deleteElements]] ignores this argument.
  */
 export interface BulkDeleteElementsArgs {
     /**
-     * Skips pre-deletion **NO ACTION** foreign key constraint validation checks, which may improve performance for large deletions.
-     * This will improve performance, but if the user supplies elements which have FK constraint violations, it will result in the delete failing and an eventual rollback.
+     * @deprecated Skipping FK constraint validation is no longer supported.
      */
     skipFKConstraintValidations?: boolean;
 }
+/**
+ * Why an element could not be deleted by [[EditTxn.deleteElements]].
+ * @beta
+ */
+export declare enum BulkDeleteFailureReason {
+    /** A row outside the delete set references it via a NO ACTION / RESTRICT / SET DEFAULT FK. */
+    ReferencedByForeignKey = 0,
+    /** It is a DefinitionElement still used by elements outside the delete set. */
+    DefinitionInUse = 1,
+    /** It is one of the elements every iModel must keep: the root Subject, the DictionaryModel partition or the RealityDataSources partition. */
+    ProtectedElement = 2,
+    /** Its handler belongs to a read-only DgnDomain. */
+    ReadOnlyDomain = 3
+}
+/**
+ * One element that could not be deleted by [[EditTxn.deleteElements]], and why.
+ * @beta
+ */
+export interface BulkDeleteFailure {
+    /** The id of the element that could not be deleted. */
+    elementId: Id64String;
+    /** Why the element could not be deleted. */
+    reason: BulkDeleteFailureReason;
+}
 /**
  * Result of a bulk element delete operation.
  * @beta
  */
 export interface BulkDeleteElementsResult {
-    /**
-     * Overall status of the bulk delete operation.
-     * - `Success`: All elements were deleted successfully. `failedIds` will be empty.
-     * - `PartialSuccess`: Some elements were deleted, but others failed. `failedIds` contains the ids that could not be deleted.
-     * - `DeletionFailed`: The delete operation failed entirely (e.g. due to an FK constraint violation). `failedIds` contains the ids that could not be deleted.
-     */
+    /** Overall status of the bulk delete operation. See [[BulkDeleteElementsStatus]]. */
     status: BulkDeleteElementsStatus;
+    /** The raw SQLite result code from the underlying SQL DELETE. Only meaningful when `status === DeletionFailed`. */
+    sqlDeleteStatus: DbResult;
     /**
-     * The raw SQLite result code from the underlying SQL DELETE statement.
-     * `DbResult.BE_SQLITE_OK` on success; a non-OK code indicates a database-level error such as a constraint violation.
+     * One entry per element that blocks the deletion, with the reason. Only populated on `ConstraintViolation`.
+     * Empty on `Success` and `DeletionFailed`.
+     * Because the whole expanded delete set is validated, a reported element may be a child or sub-model member
+     * that was not in the requested ids; its requested ancestor is not listed separately.
      */
-    sqlDeleteStatus: DbResult;
+    failures: BulkDeleteFailure[];
     /**
      * The set of element ids that could not be deleted.
-     * Empty when `status` is `Success`. Non-empty when `status` is `PartialSuccess` or `DeletionFailed`.
+     * - On `ConstraintViolation`: the unique element ids appearing in `failures`. May include cascaded descendants
+     *   that were not in the requested ids, so this is not guaranteed to be a subset of the input. Never empty.
+     *   Nothing was deleted, including requested ids that are not listed.
+     * - On `DeletionFailed`: every requested id (the iModel may be partially modified; abandon the current txn).
+     * - On `Success`: empty.
+     * @deprecated Use `failures` for a more detailed failure report.
      */
     failedIds: Id64Set;
 }
@@ -48,9 +76,9 @@ export interface BulkDeleteElementsResult {
 export declare enum BulkDeleteElementsStatus {
     /** All supplied elements were deleted successfully. */
     Success = 0,
-    /** Some elements were deleted but others could not be, typically due to foreign key constraints on the elements not being deleted. */
-    PartialSuccess = 1,
-    /** No elements were deleted. This occurs when the SQL DELETE statement itself fails, e.g. due to a FK constraint violation that prevents the entire batch from being processed. */
+    /** Nothing was deleted because some elements in the (expanded) delete set are still referenced from outside the set; see `failures` for the violators. */
+    ConstraintViolation = 1,
+    /** An internal error occurred. The iModel may be partially modified; the caller must abandon the current txn. `failures` will be empty. */
     DeletionFailed = 2
 }
 /**
@@ -96,6 +124,7 @@ export declare class EditTxn {
     verifyWriteable(): void;
     /** Start this EditTxn, making it the active transaction for the iModel.
      * @throws EditTxnError if this EditTxn is already active, another EditTxn is already active, or if unsaved changes are present.
+     * @throws IModelError if the geographic coordinate system is being restored.
      */
     start(): void;
     /** End this EditTxn, either by saving or abandoning the changes.
@@ -103,6 +132,7 @@ export declare class EditTxn {
      * @param args Save changes arguments when saving.
      * @throws EditTxnError if this EditTxn is not active.
      * @throws IModelError if saving changes fails.
+     * @throws Re-throws any error propagated by a geographic coordinate system restoration listener after completing abandonment.
      */
     end(): void;
     end(mode: "save" | "abandon", args?: string | SaveChangesArgs): void;
@@ -117,6 +147,7 @@ export declare class EditTxn {
      * @throws EditTxnError if this EditTxn is not active.
      */
     abandonChanges(): void;
+    private abandonDatabaseChanges;
     /** Save changes with additional arguments.
      * @param args Save changes arguments.
      * @throws EditTxnError if this EditTxn is not active.
@@ -198,14 +229,23 @@ export declare class EditTxn {
      */
     private collectSubtreeIds;
     /**
-     * Delete multiple elements from the iModel.
+     * Delete multiple elements from the iModel in a single bulk operation.
+     *
+     * Child elements and sub-model contents of the requested elements are deleted along with them.
+     *
+     * The operation is all-or-nothing:
+     * - On `Success`, all elements (and their children / sub-model contents) were deleted.
+     * - On `ConstraintViolation`, nothing was deleted and [[BulkDeleteElementsResult.failures]] lists every element in the
+     *   expanded delete set that is still referenced from outside the set, and why. Fix or include those referencing elements and retry.
+     * - On `DeletionFailed` (an unexpected SQLite error) the iModel may be partially modified and the caller must abandon the current txn.
+     *
      * @param ids The ids of the elements to delete. All ids must be well-formed and valid [[Id64String]]s.
-     * @param deleteOptions Options for the delete operation.
-     * @returns A result object containing information about the deletion operation success and the element ids that failed to delete (if any).
+     * @param _deleteOptions Deprecated and ignored; kept for backward compatibility of the signature.
+     * @returns A result object describing the outcome of the operation and the elements that block it (if any).
      * @throws [[ITwinError]] if any of the supplied ids are not well-formed/valid [[Id64String]]s.
      * @beta
      */
-    deleteElements(ids: Id64Array, deleteOptions?: BulkDeleteElementsArgs): BulkDeleteElementsResult;
+    deleteElements(ids: Id64Array, _deleteOptions?: BulkDeleteElementsArgs): BulkDeleteElementsResult;
     /** Insert a new aspect into the iModel.
      * @param aspectProps The properties of the new aspect.
      * @returns The newly inserted aspect Id.
@@ -303,6 +343,7 @@ export declare class EditTxn {
      */
     updateEcefLocation(ecef: EcefLocationProps): void;
     /** Update the iModel props in the database from the current in-memory state.
+     * An unchanged geographic coordinate system is not replaced or re-resolved from its dictionary identifiers.
      * @throws EditTxnError if this EditTxn is not active.
      */
     updateIModelProps(): void;
@@ -332,6 +373,7 @@ export declare class EditTxn {
  * and passed to `fn`. If `fn` returns normally (or its returned Promise resolves), the transaction
  * is committed. If `fn` throws (or its returned Promise rejects), the transaction is abandoned —
  * none of the changes made during the callback are saved — and the error is re-thrown.
+ * If abandonment also throws, logging that secondary error is attempted without allowing a logging failure to replace the callback error.
  *
  * This is the recommended way to perform a scoped unit of work on an iModel. It ensures that
  * edits are committed atomically on success and rolled back on failure, without the caller needing

package/lib/esm/EditTxn.d.ts.map

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

package/lib/esm/EditTxn.js

@@ -5,10 +5,26 @@
 /** @packageDocumentation
  * @module iModels
  */
-import { DbResult, Id64, IModelStatus, ITwinError, OpenMode } from "@itwin/core-bentley";
+import { DbResult, Id64, IModelStatus, ITwinError, Logger, OpenMode } from "@itwin/core-bentley";
 import { EcefLocation, EditTxnError, ElementError, IModelError } from "@itwin/core-common";
 import { Range3d } from "@itwin/core-geometry";
-import { _activeTxn, _cache, _instanceKeyCache, _nativeDb, _verifyChannel } from "./internal/Symbols";
+import { BackendLoggerCategory } from "./BackendLoggerCategory";
+import { _activeTxn, _cache, _instanceKeyCache, _nativeDb, _refreshGeographicCoordinateSystem, _updateIModelProps, _verifyChannel, _verifyTxnWrite } from "./internal/Symbols";
+/**
+ * Why an element could not be deleted by [[EditTxn.deleteElements]].
+ * @beta
+ */
+export var BulkDeleteFailureReason;
+(function (BulkDeleteFailureReason) {
+    /** A row outside the delete set references it via a NO ACTION / RESTRICT / SET DEFAULT FK. */
+    BulkDeleteFailureReason[BulkDeleteFailureReason["ReferencedByForeignKey"] = 0] = "ReferencedByForeignKey";
+    /** It is a DefinitionElement still used by elements outside the delete set. */
+    BulkDeleteFailureReason[BulkDeleteFailureReason["DefinitionInUse"] = 1] = "DefinitionInUse";
+    /** It is one of the elements every iModel must keep: the root Subject, the DictionaryModel partition or the RealityDataSources partition. */
+    BulkDeleteFailureReason[BulkDeleteFailureReason["ProtectedElement"] = 2] = "ProtectedElement";
+    /** Its handler belongs to a read-only DgnDomain. */
+    BulkDeleteFailureReason[BulkDeleteFailureReason["ReadOnlyDomain"] = 3] = "ReadOnlyDomain";
+})(BulkDeleteFailureReason || (BulkDeleteFailureReason = {}));
 /**
  * Status of a bulk element delete operation, mirroring the C++ `BulkDeleteStatus` enum.
  * @beta
@@ -17,9 +33,9 @@ export var BulkDeleteElementsStatus;
 (function (BulkDeleteElementsStatus) {
     /** All supplied elements were deleted successfully. */
     BulkDeleteElementsStatus[BulkDeleteElementsStatus["Success"] = 0] = "Success";
-    /** Some elements were deleted but others could not be, typically due to foreign key constraints on the elements not being deleted. */
-    BulkDeleteElementsStatus[BulkDeleteElementsStatus["PartialSuccess"] = 1] = "PartialSuccess";
-    /** No elements were deleted. This occurs when the SQL DELETE statement itself fails, e.g. due to a FK constraint violation that prevents the entire batch from being processed. */
+    /** Nothing was deleted because some elements in the (expanded) delete set are still referenced from outside the set; see `failures` for the violators. */
+    BulkDeleteElementsStatus[BulkDeleteElementsStatus["ConstraintViolation"] = 1] = "ConstraintViolation";
+    /** An internal error occurred. The iModel may be partially modified; the caller must abandon the current txn. `failures` will be empty. */
     BulkDeleteElementsStatus[BulkDeleteElementsStatus["DeletionFailed"] = 2] = "DeletionFailed";
 })(BulkDeleteElementsStatus || (BulkDeleteElementsStatus = {}));
 /**
@@ -68,14 +84,17 @@ export class EditTxn {
         this.description = description;
     }
     verifyWriteable() {
+        this.iModel[_verifyTxnWrite]();
         // Explicit transactions must always be active before writing.
         if (!this.isActive)
             EditTxnError.throwError("not-active", "EditTxn is not active", this.iModel.key);
     }
     /** Start this EditTxn, making it the active transaction for the iModel.
      * @throws EditTxnError if this EditTxn is already active, another EditTxn is already active, or if unsaved changes are present.
+     * @throws IModelError if the geographic coordinate system is being restored.
      */
     start() {
+        this.iModel[_verifyTxnWrite]();
         if (this.isActive)
             EditTxnError.throwError("already-active", "This EditTxn is already active", this.iModel.key);
         const activeTxn = this.iModel[_activeTxn];
@@ -92,9 +111,11 @@ export class EditTxn {
             this.saveChanges(args);
         }
         else {
-            this.abandonChanges();
+            this.abandonDatabaseChanges();
         }
         this.iModel[_activeTxn] = undefined;
+        if (mode === "abandon")
+            this.iModel[_refreshGeographicCoordinateSystem]();
     }
     /** Invoked when the owning iModel is closing.
      * The base implementation commits unsaved changes. Subclasses may override to customize how
@@ -110,6 +131,10 @@ export class EditTxn {
      * @throws EditTxnError if this EditTxn is not active.
      */
     abandonChanges() {
+        this.abandonDatabaseChanges();
+        this.iModel[_refreshGeographicCoordinateSystem]();
+    }
+    abandonDatabaseChanges() {
         this.verifyWriteable();
         this.iModel.clearCaches({ instanceCachesOnly: true });
         this.iModel[_nativeDb].abandonChanges();
@@ -347,14 +372,24 @@ export class EditTxn {
         return ids;
     }
     /**
-     * Delete multiple elements from the iModel.
+     * Delete multiple elements from the iModel in a single bulk operation.
+     *
+     * Child elements and sub-model contents of the requested elements are deleted along with them.
+     *
+     * The operation is all-or-nothing:
+     * - On `Success`, all elements (and their children / sub-model contents) were deleted.
+     * - On `ConstraintViolation`, nothing was deleted and [[BulkDeleteElementsResult.failures]] lists every element in the
+     *   expanded delete set that is still referenced from outside the set, and why. Fix or include those referencing elements and retry.
+     * - On `DeletionFailed` (an unexpected SQLite error) the iModel may be partially modified and the caller must abandon the current txn.
+     *
      * @param ids The ids of the elements to delete. All ids must be well-formed and valid [[Id64String]]s.
-     * @param deleteOptions Options for the delete operation.
-     * @returns A result object containing information about the deletion operation success and the element ids that failed to delete (if any).
+     * @param _deleteOptions Deprecated and ignored; kept for backward compatibility of the signature.
+     * @returns A result object describing the outcome of the operation and the elements that block it (if any).
      * @throws [[ITwinError]] if any of the supplied ids are not well-formed/valid [[Id64String]]s.
      * @beta
      */
-    deleteElements(ids, deleteOptions) {
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    deleteElements(ids, _deleteOptions) {
         this.verifyWriteable();
         const invalidIds = new Set();
         for (const id of ids) {
@@ -363,17 +398,27 @@ export class EditTxn {
         }
         if (invalidIds.size > 0)
             ITwinError.throwError({ message: `Invalid element ids: ${Array.from(invalidIds).join(", ")}`, iTwinErrorId: { scope: "imodel", key: "invalid-arguments" } });
-        const bulkDeletionResult = this.iModel[_nativeDb].deleteElements(ids, deleteOptions);
-        const finalResult = { ...bulkDeletionResult, failedIds: Id64.toIdSet(bulkDeletionResult.failedIds) };
-        if (finalResult.status === BulkDeleteElementsStatus.DeletionFailed)
-            return finalResult;
-        for (const id of ids) {
-            if (!finalResult.failedIds.has(id)) {
-                this.iModel.elements[_cache].delete({ id });
-                this.iModel.elements[_instanceKeyCache].deleteById(id);
-            }
-        }
-        return finalResult;
+        const nativeResult = this.iModel[_nativeDb].deleteElements(ids);
+        // When deletion fails with `DeletionFailed`, all requested ids are returned to maintain backward compatibilty.
+        // Once `failedIds` is deprecated, we will change this to throw instead as this is a SQLite failure.
+        const failedIds = nativeResult.status === BulkDeleteElementsStatus.DeletionFailed
+            ? new Set(ids)
+            : new Set(nativeResult.failures.map((failure) => failure.elementId));
+        const result = {
+            status: nativeResult.status,
+            sqlDeleteStatus: nativeResult.sqlDeleteStatus,
+            failures: nativeResult.failures,
+            // `failedIds` is deprecated. `failures` provides a more comprehensive error report.
+            // We still need to return the deprecated `failedIds` to maintain backward compatibility.
+            failedIds,
+        };
+        // Nothing was deleted on ConstraintViolation; on DeletionFailed the caller must abandon the txn, which restores the cached state.
+        if (result.status !== BulkDeleteElementsStatus.Success)
+            return result;
+        // Native deletion also nulls logical navigation properties on surviving elements that referenced the deleted ones,
+        // so evicting only the requested ids would leave stale cached referrers. Clear all instance caches.
+        this.iModel.clearCaches({ instanceCachesOnly: true });
+        return result;
     }
     /** Insert a new aspect into the iModel.
      * @param aspectProps The properties of the new aspect.
@@ -643,11 +688,12 @@ export class EditTxn {
         this.updateIModelProps();
     }
     /** Update the iModel props in the database from the current in-memory state.
+     * An unchanged geographic coordinate system is not replaced or re-resolved from its dictionary identifiers.
      * @throws EditTxnError if this EditTxn is not active.
      */
     updateIModelProps() {
         this.verifyWriteable();
-        this.iModel[_nativeDb].updateIModelProps(this.iModel.toJSON());
+        this.iModel[_updateIModelProps]();
     }
     static _settingPropNamespace = "settings";
     static _viewStoreProperty = { namespace: "itwinjs", name: "DefaultViewStore" };
@@ -700,25 +746,34 @@ export function withEditTxn(iModel, saveArgsOrFn, maybeFn) {
         throw new Error("withEditTxn requires a callback");
     const txn = new EditTxn(iModel, "");
     txn.start();
+    const abandonOnError = (error) => {
+        try {
+            if (txn.isActive)
+                txn.end("abandon");
+        }
+        catch (abandonError) {
+            try {
+                Logger.logError(BackendLoggerCategory.IModelDb, abandonError);
+            }
+            catch {
+                throw error;
+            }
+        }
+        throw error;
+    };
     try {
         const result = fn(txn);
         if (result instanceof Promise) {
             return result.then((value) => {
                 txn.end("save", saveArgs);
                 return value;
-            }, (err) => {
-                if (txn.isActive)
-                    txn.end("abandon");
-                throw err;
-            });
+            }, abandonOnError);
         }
         txn.end("save", saveArgs);
         return result;
     }
     catch (err) {
-        if (txn.isActive)
-            txn.end("abandon");
-        throw err;
+        return abandonOnError(err);
     }
 }
 //# sourceMappingURL=EditTxn.js.map