@itwin/core-backend 5.8.2 → 5.9.0-dev.10

package/lib/cjs/EditTxn.d.ts

@@ -0,0 +1,262 @@
+/** @packageDocumentation
+ * @module iModels
+ */
+import { Id64Arg, Id64Array, Id64Set, Id64String } from "@itwin/core-bentley";
+import { EcefLocationProps, ElementAspectProps, ElementProps, FilePropertyProps, ModelProps, RelationshipProps, SaveChangesArgs } from "@itwin/core-common";
+import { Range3dProps } from "@itwin/core-geometry";
+import type { CloudSqlite } from "./CloudSqlite";
+import type { ImplicitWriteEnforcement } from "./IModelHost";
+import type { IModelDb, InsertElementOptions, UpdateModelOptions } from "./IModelDb";
+import type { SettingsContainer } from "./workspace/Settings";
+/**
+ * Represents an explicit editing transaction for an iModel.
+ *
+ * An explicit EditTxn lets callers define a deliberate unit of work by choosing when editing
+ * starts (`start`) and how it ends (`end()` / `end("save")` or `end("abandon")`). This avoids mixing
+ * unrelated edits into one implicit unit of work and makes save/rollback boundaries explicit.
+ *
+ * Explicit EditTxn instances must be active before mutating operations are performed, regardless of enforcement level.
+ * In other words, explicit transaction behavior is independent of `implicitWriteEnforcement`.
+ *
+ * @see [EditTxn transaction model and migration guidance]($docs/learning/backend/EditTxn.md)
+ *
+ * *During indirect changes (commit processing):* Use callback args (`indirectEditTxn`) in callbacks like
+ * [[Relationship.onRootChangedArg]] and [[Relationship.onDeletedDependencyArg]] that fire during indirect processing.
+ *
+ * @beta
+ */
+export declare class EditTxn {
+    /** Controls how writes through the implicit transaction are handled.
+     *
+     * This does not relax activation requirements for explicit transactions: explicit EditTxn writes
+     * must always come from the active EditTxn.
+     *
+     * - `allow`: allow implicit writes for backwards compatibility, even while an explicit EditTxn is active.
+     * - `log`: allow implicit writes but log `implicit-txn-write-disallowed` errors.
+     * - `throw`: reject implicit writes with `implicit-txn-write-disallowed`.
+     *
+     * This is initialized from [[IModelHostOptions.implicitWriteEnforcement]] during [[IModelHost.startup]].
+     *
+     * Defaults to `allow` for backwards compatibility.
+     * @beta
+     */
+    static implicitWriteEnforcement: ImplicitWriteEnforcement;
+    /** The iModel this EditTxn may modify. */
+    readonly iModel: IModelDb;
+    /** Default description passed to [[saveChanges]] when saving this transaction. */
+    description: string;
+    /** True if this transaction currently owns the iModel write surface. */
+    get isActive(): boolean;
+    constructor(iModel: IModelDb, description: string);
+    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.
+     */
+    start(): void;
+    /** End this EditTxn, either by saving or abandoning the changes.
+     * @param mode Whether to "save" or "abandon" the changes. Defaults to "save".
+     * @param args Save changes arguments when saving.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @throws IModelError if saving changes fails.
+     */
+    end(): void;
+    end(mode: "save" | "abandon", args?: string | SaveChangesArgs): void;
+    /** Invoked when the owning iModel is closing.
+     * The base implementation commits unsaved changes. Subclasses may override to customize how
+     * their changes are handled before the iModel closes.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @throws IModelError if saving on close fails.
+     */
+    onClose(): void;
+    /** Abandon database changes while keeping this EditTxn active.
+     * @throws EditTxnError if this EditTxn is not active.
+     */
+    abandonChanges(): void;
+    /** Save changes with additional arguments.
+     * @param args Save changes arguments.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @throws IModelError if the iModel is readonly, if indirect changes are active, or if the native save fails.
+     */
+    saveChanges(args?: string | SaveChangesArgs): void;
+    /** Insert a new element into the iModel.
+     * @param elProps The properties of the new element.
+     * @returns The newly inserted element's Id.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @throws [[ITwinError]] if insertion fails.
+     */
+    insertElement(elProps: ElementProps, options?: InsertElementOptions): Id64String;
+    /** Update an existing element in the iModel.
+     * @param elProps The properties to update.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @throws [[ITwinError]] if update fails.
+     */
+    updateElement<T extends ElementProps>(elProps: Partial<T>): void;
+    /** Delete elements from the iModel.
+     * @param ids The Ids of the elements to delete.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @throws [[ITwinError]] if deletion fails.
+     */
+    deleteElement(ids: Id64Arg): void;
+    /** Insert a new aspect into the iModel.
+     * @param aspectProps The properties of the new aspect.
+     * @returns The newly inserted aspect Id.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @throws IModelError if insertion fails.
+     */
+    insertAspect(aspectProps: ElementAspectProps): Id64String;
+    /** Update an existing aspect in the iModel.
+     * @param aspectProps The properties of the aspect to update.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @throws IModelError if update fails.
+     */
+    updateAspect(aspectProps: ElementAspectProps): void;
+    /** Delete one or more aspects from the iModel.
+     * @param aspectInstanceIds The Ids of the aspects to delete.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @throws IModelError if deletion fails.
+     */
+    deleteAspect(aspectInstanceIds: Id64Arg): void;
+    /** Delete definition elements from the iModel when they are not referenced.
+     * @param definitionElementIds The Ids of the definition elements to attempt to delete.
+     * @returns The set of definition elements that were still in use and therefore not deleted.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @throws IModelError if usage queries fail.
+     */
+    deleteDefinitionElements(definitionElementIds: Id64Array): Id64Set;
+    /** Insert a new model into the iModel.
+     * @param props The data for the new model.
+     * @returns The newly inserted model's Id.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @throws IModelError if insertion fails.
+     */
+    insertModel(props: ModelProps): Id64String;
+    /** Update an existing model in the iModel.
+     * @param props the properties of the model to change
+     * @throws EditTxnError if this EditTxn is not active.
+     * @throws IModelError if update fails.
+     */
+    updateModel(props: UpdateModelOptions): void;
+    /** Update the geometry guid of a model.
+     * @param modelId The Id of the model to update.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @throws IModelError if the update fails.
+     */
+    updateGeometryGuid(modelId: Id64String): void;
+    /** Delete models from the iModel.
+     * @param ids The Ids of the models to delete.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @throws IModelError if deletion fails.
+     */
+    deleteModel(ids: Id64Arg): void;
+    /** Insert a new relationship into the iModel.
+     * @param props The properties of the new relationship.
+     * @returns The Id of the newly inserted relationship.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @throws IModelError if the class is invalid for link-table insertion.
+     */
+    insertRelationship(props: RelationshipProps): Id64String;
+    /** Update an existing relationship in the iModel.
+     * @param props the properties of the relationship to update.
+     * @throws EditTxnError if this EditTxn is not active.
+     */
+    updateRelationship(props: RelationshipProps): void;
+    /** Delete a relationship from the iModel.
+     * @param props The properties of the relationship to delete.
+     * @throws EditTxnError if this EditTxn is not active.
+     */
+    deleteRelationship(props: RelationshipProps): void;
+    /** Delete multiple relationships from the iModel.
+     * @param props The properties of the relationships to delete.
+     * @throws EditTxnError if this EditTxn is not active.
+     */
+    deleteRelationships(props: ReadonlyArray<RelationshipProps>): void;
+    /** Save a file property to the iModel.
+     * @param prop The file property to save.
+     * @param strValue String value.
+     * @param blobVal Blob value.
+     * @throws EditTxnError if this EditTxn is not active.
+     */
+    saveFileProperty(prop: FilePropertyProps, strValue: string | undefined, blobVal?: Uint8Array): void;
+    /** Delete a file property from the iModel.
+     * @param prop The file property to delete.
+     * @throws EditTxnError if this EditTxn is not active.
+     */
+    deleteFileProperty(prop: FilePropertyProps): void;
+    /** Update the project extents of the iModel.
+     * @param newExtents The new project extents.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @throws IModelError if extents are invalid.
+     */
+    updateProjectExtents(newExtents: Range3dProps): void;
+    /** Update the ECEF location of the iModel.
+     * @param ecef The new ECEF location.
+     * @throws EditTxnError if this EditTxn is not active.
+     */
+    updateEcefLocation(ecef: EcefLocationProps): void;
+    /** Update the iModel props in the database from the current in-memory state.
+     * @throws EditTxnError if this EditTxn is not active.
+     */
+    updateIModelProps(): void;
+    private static readonly _settingPropNamespace;
+    private static readonly _viewStoreProperty;
+    /** Save a `SettingDictionary` in this iModel.
+     * @param name The name for the SettingDictionary. If a dictionary by that name already exists, its value is replaced.
+     * @param dict The SettingDictionary object to stringify and save.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @beta
+     */
+    saveSettingDictionary(name: string, dict: SettingsContainer): void;
+    /** Delete a SettingDictionary from this iModel.
+     * @param name The name of the dictionary to delete.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @beta
+     */
+    deleteSettingDictionary(name: string): void;
+    /** Save a default ViewStore container reference in this iModel.
+     * @param arg The cloud container properties for the ViewStore.
+     * @throws EditTxnError if this EditTxn is not active.
+     * @beta
+     */
+    saveDefaultViewStore(arg: CloudSqlite.ContainerProps): void;
+}
+/** Execute a callback within an explicit editing transaction. A new [[EditTxn]] is created, started,
+ * 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.
+ *
+ * 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
+ * to manage `start` / `end` manually.
+ *
+ * @param iModel The iModel to edit.
+ * @param fn A callback that receives the active [[EditTxn]] and performs edits.
+ * @returns The value returned by `fn`.
+ * @throws EditTxnError if the transaction cannot be started (e.g. unsaved changes or another EditTxn is active).
+ * @throws Re-throws any error thrown by `fn` after abandoning the transaction.
+ * @beta
+ */
+export declare function withEditTxn<T>(iModel: IModelDb, fn: (txn: EditTxn) => T): T;
+/** Execute a callback within an explicit editing transaction, supplying commit arguments.
+ * @param iModel The iModel to edit.
+ * @param saveArgs Description or structured arguments passed to [[EditTxn.saveChanges]] on save.
+ * @param fn A callback that receives the active [[EditTxn]] and performs edits.
+ * @returns The value returned by `fn`.
+ * @beta
+ */
+export declare function withEditTxn<T>(iModel: IModelDb, saveArgs: string | SaveChangesArgs, fn: (txn: EditTxn) => T): T;
+/** Execute an async callback within an explicit editing transaction.
+ * @param iModel The iModel to edit.
+ * @param fn An async callback that receives the active [[EditTxn]] and performs edits.
+ * @returns A Promise that resolves to the value returned by `fn`.
+ * @beta
+ */
+export declare function withEditTxn<T>(iModel: IModelDb, fn: (txn: EditTxn) => Promise<T>): Promise<T>;
+/** Execute an async callback within an explicit editing transaction, supplying commit arguments.
+ * @param iModel The iModel to edit.
+ * @param saveArgs Description or structured arguments passed to [[EditTxn.saveChanges]] on save.
+ * @param fn An async callback that receives the active [[EditTxn]] and performs edits.
+ * @returns A Promise that resolves to the value returned by `fn`.
+ * @beta
+ */
+export declare function withEditTxn<T>(iModel: IModelDb, saveArgs: string | SaveChangesArgs, fn: (txn: EditTxn) => Promise<T>): Promise<T>;
+//# sourceMappingURL=EditTxn.d.ts.map

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

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