@itwin/core-backend 5.12.0-dev.2 → 5.12.0-dev.6

package/lib/esm/IModelDb.js

@@ -9,7 +9,7 @@ import * as fs from "fs";
 import { join } from "path";
 import * as touch from "touch";
 import { assert, BeEvent, BentleyStatus, ChangeSetStatus, DbChangeStage, DbConflictCause, DbConflictResolution, DbResult, Guid, Id64, IModelStatus, JsonUtils, Logger, LogLevel, LRUMap, OpenMode } from "@itwin/core-bentley";
-import { BriefcaseIdValue, Code, DomainOptions, ECJsNames, ECSqlReader, EditTxnError, EntityMetaData, FontMap, IModel, IModelError, IModelNotFoundResponse, ProfileOptions, QueryRowFormat, resolveNavPropId, SchemaState, ViewStoreError, ViewStoreRpc } from "@itwin/core-common";
+import { BriefcaseIdValue, Code, DomainOptions, ECJsNames, ECSqlReader, EditTxnError, EntityMetaData, FontMap, IModel, IModelError, IModelNotFoundResponse, ProfileOptions, QueryBinder, QueryRowFormat, resolveNavPropId, SchemaState, ViewStoreError, ViewStoreRpc } from "@itwin/core-common";
 import { Range2d, Range3d } from "@itwin/core-geometry";
 import { BackendLoggerCategory } from "./BackendLoggerCategory";
 import { BriefcaseManager } from "./BriefcaseManager";
@@ -163,7 +163,7 @@ export class IModelDb extends IModel {
     _schemaMap;
     _schemaContext;
     _schemasPromise;
-    /** @deprecated in 5.0.0 - will not be removed until after 2026-06-13. Use [[fonts]]. */
+    /** @deprecated in 5.0.0 - might be removed in next major version. Use [[fonts]]. */
     _fontMap; // eslint-disable-line @typescript-eslint/no-deprecated
     _fonts = createIModelDbFonts(this);
     _workspace;
@@ -238,7 +238,7 @@ export class IModelDb extends IModel {
     restartDefaultTxn() {
         this[_nativeDb].restartDefaultTxn();
     }
-    /** @deprecated in 5.0.0 - will not be removed until after 2026-06-13. Use [[fonts]]. */
+    /** @deprecated in 5.0.0 - might be removed in next major version. Use [[fonts]]. */
     get fontMap() {
         return this._fontMap ?? (this._fontMap = new FontMap(this[_nativeDb].readFontMap())); // eslint-disable-line @typescript-eslint/no-deprecated
     }
@@ -521,7 +521,7 @@ export class IModelDb extends IModel {
      * @returns the value returned by `callback`.
      * @see [[withStatement]]
      * @public
-     * @deprecated in 4.11 - will not be removed until after 2026-06-13.  Use [[createQueryReader]] instead.
+     * @deprecated in 4.11 - might be removed in next major version. Use [[createQueryReader]] instead.
      */
     // eslint-disable-next-line @typescript-eslint/no-deprecated
     withPreparedStatement(ecsql, callback, logErrors = true) {
@@ -553,7 +553,7 @@ export class IModelDb extends IModel {
      * @returns the value returned by `callback`.
      * @see [[withPreparedStatement]]
      * @public
-     * @deprecated in 4.11 - will not be removed until after 2026-06-13.  Use [[createQueryReader]] instead.
+     * @deprecated in 4.11 - might be removed in next major version. Use [[createQueryReader]] instead.
      */
     // eslint-disable-next-line @typescript-eslint/no-deprecated
     withStatement(ecsql, callback, logErrors = true) {
@@ -774,19 +774,17 @@ export class IModelDb extends IModel {
         if (typeof params.offset === "number" && params.offset > 0)
             sql += ` OFFSET ${params.offset}`;
         const ids = new Set();
-        // eslint-disable-next-line @typescript-eslint/no-deprecated
-        this.withPreparedStatement(sql, (stmt) => {
-            if (params.bindings)
-                stmt.bindValues(params.bindings);
-            for (const row of stmt) {
-                if (row.id !== undefined) {
-                    ids.add(row.id);
+        this.withQueryReader(sql, (reader) => {
+            for (const row of reader) {
+                const id = row[0];
+                if (id !== undefined) {
+                    ids.add(id);
                     if (ids.size > IModelDb.maxLimit) {
                         throw new IModelError(IModelStatus.BadRequest, "Max LIMIT exceeded in SELECT statement");
                     }
                 }
             }
-        });
+        }, QueryBinder.from(params.bindings));
         return ids;
     }
     clearCaches(params) {
@@ -875,7 +873,7 @@ export class IModelDb extends IModel {
         }
     }
     /** @internal
-     * @deprecated in 4.8 - will not be removed until after 2026-06-13. Use `txns.reverseTxns`.
+     * @deprecated in 4.8 - might be removed in next major version. Use `txns.reverseTxns`.
      */
     reverseTxns(numOperations) {
         return this[_nativeDb].reverseTxns(numOperations);
@@ -1242,7 +1240,7 @@ export class IModelDb extends IModel {
     }
     /** The registry of entity metadata for this iModel.
      * @internal
-     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use `getSchemaView()` from the `iModel` instead.
+     * @deprecated in 5.0 - might be removed in next major version. Use `getSchemaView()` from the `iModel` instead.
      *
      * @example
      * ```typescript
@@ -1357,7 +1355,7 @@ export class IModelDb extends IModel {
      * @param sql The ECSQL statement to prepare
      * @param logErrors Determines if error will be logged if statement fail to prepare
      * @throws [[IModelError]] if there is a problem preparing the statement.
-     * @deprecated in 4.11 - will not be removed until after 2026-06-13.  Use [IModelDb.createQueryReader]($backend) or [ECDb.createQueryReader]($backend) to query.
+     * @deprecated in 4.11 - might be removed in next major version. Use [IModelDb.createQueryReader]($backend) or [ECDb.createQueryReader]($backend) to query.
      */
     // eslint-disable-next-line @typescript-eslint/no-deprecated
     prepareStatement(sql, logErrors = true) {
@@ -1369,7 +1367,7 @@ export class IModelDb extends IModel {
     /** Prepare an ECSQL statement.
      * @param sql The ECSQL statement to prepare
      * @returns `undefined` if there is a problem preparing the statement.
-     * @deprecated in 4.11 - will not be removed until after 2026-06-13.  Use [IModelDb.createQueryReader]($backend) or [ECDb.createQueryReader]($backend) to query.
+     * @deprecated in 4.11 - might be removed in next major version. Use [IModelDb.createQueryReader]($backend) or [ECDb.createQueryReader]($backend) to query.
      */
     // eslint-disable-next-line @typescript-eslint/no-deprecated
     tryPrepareStatement(sql) {
@@ -1419,7 +1417,7 @@ export class IModelDb extends IModel {
     }
     /** Get metadata for a class. This method will load the metadata from the iModel into the cache as a side-effect, if necessary.
      * @throws [[IModelError]] if the metadata cannot be found nor loaded.
-     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use `getSchemaView()` on the iModel and call `view.findClass(...)` instead.
+     * @deprecated in 5.0 - might be removed in next major version. Use `getSchemaView()` on the iModel and call `view.findClass(...)` instead.
      *
      * @example
      *  * ```typescript
@@ -1446,7 +1444,7 @@ export class IModelDb extends IModel {
         return metadata;
     }
     /** Identical to [[getMetaData]], except it returns `undefined` instead of throwing an error if the metadata cannot be found nor loaded.
-     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use `getSchemaView()` on the iModel and call `view.findClass(...)` instead.
+     * @deprecated in 5.0 - might be removed in next major version. Use `getSchemaView()` on the iModel and call `view.findClass(...)` instead.
      *
      * @example
      *  * ```typescript
@@ -1475,7 +1473,7 @@ export class IModelDb extends IModel {
      * @param func The callback to be invoked on each property
      * @param includeCustom If true (default), include custom-handled properties in the iteration. Otherwise, skip custom-handled properties.
      * @note Custom-handled properties are core properties that have behavior enforced by C++ handlers.
-     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use `getSchemaView()` on the iModel and iterate `view.findClass(classFullName)?.getProperties()` instead.
+     * @deprecated in 5.0 - might be removed in next major version. Use `getSchemaView()` on the iModel and iterate `view.findClass(classFullName)?.getProperties()` instead.
      *
      * @example
      * ```typescript
@@ -1502,7 +1500,7 @@ export class IModelDb extends IModel {
      * @param func The callback to be invoked on each property
      * @param includeCustom If true (default), include custom-handled properties in the iteration. Otherwise, skip custom-handled properties.
      * @note Custom-handled properties are core properties that have behavior enforced by C++ handlers.
-     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use `getSchemaView()` on the iModel and iterate `view.findClass(classFullName)?.getProperties()` instead.
+     * @deprecated in 5.0 - might be removed in next major version. Use `getSchemaView()` on the iModel and iterate `view.findClass(classFullName)?.getProperties()` instead.
      *
      * @example
      * ```typescript
@@ -1533,7 +1531,7 @@ export class IModelDb extends IModel {
     }
     /**
      * @internal
-     * @deprecated in 5.0 - will not be removed until after 2026-06-13. Please use `schemaContext` from `iModel` instead to get metadata.
+     * @deprecated in 5.0 - might be removed in next major version. Please use `schemaContext` from `iModel` instead to get metadata.
      */
     loadMetaData(classFullName) {
         // eslint-disable-next-line @typescript-eslint/no-deprecated
@@ -1585,17 +1583,15 @@ export class IModelDb extends IModel {
      */
     querySchemaVersionNumbers(schemaName) {
         const sql = `SELECT VersionMajor,VersionWrite,VersionMinor FROM ECDbMeta.ECSchemaDef WHERE Name=:schemaName LIMIT 1`;
-        // eslint-disable-next-line @typescript-eslint/no-deprecated
-        return this.withPreparedStatement(sql, (statement) => {
-            statement.bindString("schemaName", schemaName);
-            if (DbResult.BE_SQLITE_ROW === statement.step()) {
-                const read = statement.getValue(0).getInteger(); // ECSchemaDef.VersionMajor --> semver.major
-                const write = statement.getValue(1).getInteger(); // ECSchemaDef.VersionWrite --> semver.minor
-                const minor = statement.getValue(2).getInteger(); // ECSchemaDef.VersionMinor --> semver.patch
+        return this.withQueryReader(sql, (reader) => {
+            if (reader.step()) {
+                const read = reader.current[0]; // ECSchemaDef.VersionMajor --> semver.major
+                const write = reader.current[1]; // ECSchemaDef.VersionWrite --> semver.minor
+                const minor = reader.current[2]; // ECSchemaDef.VersionMinor --> semver.patch
                 return new ECVersion(read, write, minor);
             }
             return undefined;
-        });
+        }, new QueryBinder().bindString("schemaName", schemaName));
     }
     /** Returns true if the specified schema exists in the iModel and is no older than the specified minimum version.
      * @beta
@@ -2050,14 +2046,12 @@ function processSchemaWriteStatus(status) {
          */
         queryLastModifiedTime(modelId) {
             const sql = `SELECT LastMod FROM ${Model.classFullName} WHERE ECInstanceId=:modelId`;
-            // eslint-disable-next-line @typescript-eslint/no-deprecated
-            return this._iModel.withPreparedStatement(sql, (statement) => {
-                statement.bindId("modelId", modelId);
-                if (DbResult.BE_SQLITE_ROW === statement.step()) {
-                    return statement.getValue(0).getDateTime();
+            return this._iModel.withQueryReader(sql, (reader) => {
+                if (reader.step()) {
+                    return reader.current[0];
                 }
                 throw new IModelError(IModelStatus.InvalidId, `Can't get lastMod time for Model ${modelId}`);
-            });
+            }, new QueryBinder().bindId("modelId", modelId));
         }
         /** Get the Model with the specified identifier.
          * @param modelId The Model identifier.
@@ -2385,13 +2379,11 @@ function processSchemaWriteStatus(status) {
          */
         queryLastModifiedTime(elementId) {
             const sql = "SELECT LastMod FROM BisCore:Element WHERE ECInstanceId=:elementId";
-            // eslint-disable-next-line @typescript-eslint/no-deprecated
-            return this._iModel.withPreparedStatement(sql, (statement) => {
-                statement.bindId("elementId", elementId);
-                if (DbResult.BE_SQLITE_ROW === statement.step())
-                    return statement.getValue(0).getDateTime();
+            return this._iModel.withQueryReader(sql, (reader) => {
+                if (reader.step())
+                    return reader.current[0];
                 throw new IModelError(IModelStatus.InvalidId, `Can't get lastMod time for Element ${elementId}`);
-            });
+            }, new QueryBinder().bindId("elementId", elementId));
         }
         /** Create a new instance of an element.
          * @param elProps The properties of the new element.
@@ -2466,15 +2458,13 @@ function processSchemaWriteStatus(status) {
          */
         queryChildren(elementId) {
             const sql = "SELECT ECInstanceId FROM BisCore:Element WHERE Parent.Id=:elementId";
-            // eslint-disable-next-line @typescript-eslint/no-deprecated
-            return this._iModel.withPreparedStatement(sql, (statement) => {
-                statement.bindId("elementId", elementId);
+            return this._iModel.withQueryReader(sql, (reader) => {
                 const childIds = [];
-                while (DbResult.BE_SQLITE_ROW === statement.step()) {
-                    childIds.push(statement.getValue(0).getId());
+                for (const row of reader) {
+                    childIds.push(row[0]);
                 }
                 return childIds;
-            });
+            }, new QueryBinder().bindId("elementId", elementId));
         }
         /** Query for the parent of the specified element.
          * @param elementId The element to check for a parent
@@ -2482,14 +2472,12 @@ function processSchemaWriteStatus(status) {
          * @throws [[IModelError]] if the element does not exist
          */
         queryParent(elementId) {
-            // eslint-disable-next-line @typescript-eslint/no-deprecated
-            return this._iModel.withPreparedStatement(`select parent.id from ${Element.classFullName} where ecinstanceid=?`, (stmt) => {
-                stmt.bindId(1, elementId);
-                if (stmt.step() !== DbResult.BE_SQLITE_ROW)
+            return this._iModel.withQueryReader(`select parent.id from ${Element.classFullName} where ecinstanceid=?`, (reader) => {
+                if (!reader.step())
                     throw new IModelError(IModelStatus.NotFound, `Element=${elementId}`);
-                const value = stmt.getValue(0);
-                return value.isNull ? undefined : value.getId();
-            });
+                const value = reader.current[0];
+                return value ?? undefined;
+            }, new QueryBinder().bindId(1, elementId));
         }
         /** Returns true if the specified Element has a sub-model.
          * @see [[IModelDb.Models.getSubModel]]
@@ -2499,11 +2487,9 @@ function processSchemaWriteStatus(status) {
                 return false; // Special case since the RepositoryModel does not sub-model the root Subject
             // A sub-model will have the same Id value as the element it is describing
             const sql = "SELECT ECInstanceId FROM BisCore:Model WHERE ECInstanceId=:elementId";
-            // eslint-disable-next-line @typescript-eslint/no-deprecated
-            return this._iModel.withPreparedStatement(sql, (statement) => {
-                statement.bindId("elementId", elementId);
-                return DbResult.BE_SQLITE_ROW === statement.step();
-            });
+            return this._iModel.withQueryReader(sql, (reader) => {
+                return reader.step();
+            }, new QueryBinder().bindId("elementId", elementId));
         }
         /** Get the root subject element. */
         getRootSubject() { return this.getElement(IModel.rootSubjectId); }
@@ -2513,37 +2499,33 @@ function processSchemaWriteStatus(status) {
          * @internal
          */
         _queryAspects(elementId, fromClassFullName, excludedClassFullNames) {
-            const sql = `SELECT ECInstanceId,ECClassId FROM ${fromClassFullName} WHERE Element.Id=:elementId ORDER BY ECClassId,ECInstanceId`; // ORDER BY to maximize statement reuse
-            // eslint-disable-next-line @typescript-eslint/no-deprecated
-            return this._iModel.withPreparedStatement(sql, (statement) => {
-                statement.bindId("elementId", elementId);
+            const sql = `SELECT ECInstanceId, ec_classname(ECClassId, 's:c') FROM ${fromClassFullName} WHERE Element.Id=:elementId ORDER BY ECClassId,ECInstanceId`; // ORDER BY to maximize statement reuse
+            return this._iModel.withQueryReader(sql, (reader) => {
                 const aspects = [];
-                while (DbResult.BE_SQLITE_ROW === statement.step()) {
-                    const aspectInstanceId = statement.getValue(0).getId();
-                    const aspectClassFullName = statement.getValue(1).getClassNameForClassId().replace(".", ":");
+                for (const row of reader) {
+                    const aspectInstanceId = row[0];
+                    const aspectClassFullName = row[1];
                     if ((undefined === excludedClassFullNames) || (!excludedClassFullNames.has(aspectClassFullName))) {
                         aspects.push(this._queryAspect(aspectInstanceId, aspectClassFullName));
                     }
                 }
                 return aspects;
-            });
+            }, new QueryBinder().bindId("elementId", elementId));
         }
         /** Query for aspect by ECInstanceId
          * @throws [[IModelError]]
          */
         _queryAspect(aspectInstanceId, aspectClassName) {
-            const sql = `SELECT * FROM ${aspectClassName} WHERE ECInstanceId=:aspectInstanceId`;
-            // eslint-disable-next-line @typescript-eslint/no-deprecated
-            const aspect = this._iModel.withPreparedStatement(sql, (statement) => {
-                statement.bindId("aspectInstanceId", aspectInstanceId);
-                if (DbResult.BE_SQLITE_ROW === statement.step()) {
-                    const aspectProps = statement.getRow(); // start with everything that SELECT * returned
-                    aspectProps.classFullName = aspectProps.className.replace(".", ":"); // add in property required by EntityProps
-                    aspectProps.className = undefined; // clear property from SELECT * that we don't want in the final instance
+            const sql = `SELECT *, ec_classname(ECClassId, 's:c') classFullName FROM ${aspectClassName} WHERE ECInstanceId=:aspectInstanceId`;
+            const aspect = this._iModel.withQueryReader(sql, (reader) => {
+                if (reader.step()) {
+                    const aspectProps = { ...reader.current.toRow() }; // start with everything that SELECT * returned; classFullName is supplied by the ec_classname alias
+                    aspectProps.className = undefined; // clear the raw ECClassId-derived property from SELECT * that we don't want in the final instance
                     return aspectProps;
                 }
                 return undefined;
-            });
+                // eslint-disable-next-line @typescript-eslint/no-deprecated
+            }, new QueryBinder().bindId("aspectInstanceId", aspectInstanceId), { rowFormat: QueryRowFormat.UseJsPropertyNames });
             if (undefined === aspect) {
                 throw new IModelError(IModelStatus.NotFound, `ElementAspect not found ${aspectInstanceId}, ${aspectClassName}`);
             }
@@ -2553,12 +2535,10 @@ function processSchemaWriteStatus(status) {
          * @throws [[IModelError]]
          */
         getAspect(aspectInstanceId) {
-            const sql = "SELECT ECClassId FROM BisCore:ElementAspect WHERE ECInstanceId=:aspectInstanceId";
-            // eslint-disable-next-line @typescript-eslint/no-deprecated
-            const aspectClassFullName = this._iModel.withPreparedStatement(sql, (statement) => {
-                statement.bindId("aspectInstanceId", aspectInstanceId);
-                return (DbResult.BE_SQLITE_ROW === statement.step()) ? statement.getValue(0).getClassNameForClassId().replace(".", ":") : undefined;
-            });
+            const sql = "SELECT ec_classname(ECClassId, 's:c') FROM BisCore:ElementAspect WHERE ECInstanceId=:aspectInstanceId";
+            const aspectClassFullName = this._iModel.withQueryReader(sql, (reader) => {
+                return reader.step() ? reader.current[0] : undefined;
+            }, new QueryBinder().bindId("aspectInstanceId", aspectInstanceId));
             if (undefined === aspectClassFullName) {
                 throw new IModelError(IModelStatus.NotFound, `ElementAspect not found ${aspectInstanceId}`);
             }
@@ -2566,13 +2546,12 @@ function processSchemaWriteStatus(status) {
         }
         static classMap = new Map();
         runInstanceQuery(sql, elementId, excludedClassFullNames) {
-            // eslint-disable-next-line @typescript-eslint/no-deprecated
-            return this._iModel.withPreparedStatement(sql, (statement) => {
-                statement.bindId("elementId", elementId);
+            return this._iModel.withQueryReader(sql, (reader) => {
                 const aspects = [];
-                while (DbResult.BE_SQLITE_ROW === statement.step()) {
+                for (const queryRow of reader) {
                     const row = {};
-                    const parsedRow = JSON.parse(statement.getValue(0).getString());
+                    const rawInstance = queryRow[0];
+                    const parsedRow = typeof rawInstance === "string" ? JSON.parse(rawInstance) : rawInstance;
                     // eslint-disable-next-line guard-for-in
                     for (const key in parsedRow) {
                         const jsName = ECJsNames.toJsName(key[0].toUpperCase() + key.substring(1));
@@ -2585,7 +2564,7 @@ function processSchemaWriteStatus(status) {
                         aspects.push(this._iModel.constructEntity(aspectProps));
                 }
                 return aspects;
-            });
+            }, new QueryBinder().bindId("elementId", elementId));
         }
         /** Get the ElementAspect instances that are owned by the specified element.
          * @param elementId Get ElementAspects associated with this Element
@@ -2616,14 +2595,15 @@ function processSchemaWriteStatus(status) {
             let classIdList = IModelDb.Elements.classMap.get(aspectClassFullName);
             if (classIdList === undefined) {
                 const classIds = [];
-                // eslint-disable-next-line @typescript-eslint/no-deprecated
-                this._iModel.withPreparedStatement(`select SourceECInstanceId from meta.ClassHasAllBaseClasses where TargetECInstanceId = (select ECInstanceId from meta.ECClassDef where Name='${fullClassName[1]}'
-        and Schema.Id = (select ECInstanceId from meta.ECSchemaDef where Name='${fullClassName[0]}')) and SourceECInstanceId != TargetECInstanceId`, 
-                // eslint-disable-next-line @typescript-eslint/no-deprecated
-                (statement) => {
-                    while (statement.step() === DbResult.BE_SQLITE_ROW)
-                        classIds.push(statement.getValue(0).getId());
-                });
+                const sql = `select SourceECInstanceId from meta.ClassHasAllBaseClasses where TargetECInstanceId = (select ECInstanceId from meta.ECClassDef where Name=:className
+        and Schema.Id = (select ECInstanceId from meta.ECSchemaDef where Name=:schemaName)) and SourceECInstanceId != TargetECInstanceId`;
+                this._iModel.withQueryReader(sql, (reader) => {
+                    for (const row of reader) {
+                        classIds.push(row[0]);
+                    }
+                }, new QueryBinder()
+                    .bindString("className", fullClassName[1])
+                    .bindString("schemaName", fullClassName[0]));
                 if (classIds.length > 0) {
                     classIdList = classIds.join(",");
                     IModelDb.Elements.classMap.set(aspectClassFullName, classIdList);
@@ -2875,7 +2855,7 @@ function processSchemaWriteStatus(status) {
         }
         /** Set the default view property the iModel.
          * @param viewId The Id of the ViewDefinition to use as the default
-         * @deprecated in 4.2.0 - will not be removed until after 2026-06-13. Avoid setting this property - it is not practical for one single view to serve the needs of the many applications
+         * @deprecated in 4.2.0 - might be removed in next major version. Avoid setting this property - it is not practical for one single view to serve the needs of the many applications
          * that might wish to view the contents of the iModel.
          */
         setDefaultViewId(viewId) {