@itwin/core-backend 4.11.0-dev.2 → 4.11.0-dev.4

package/lib/cjs/ECSqlStatement.js

@@ -7,7 +7,7 @@
  * @module ECSQL
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ECSqlValueIterator = exports.ECSqlValue = exports.ECSqlBinder = exports.ECSqlStatement = exports.ECSqlInsertResult = void 0;
+exports.ECSqlValueIterator = exports.ECSqlValue = exports.ECSqlBinder = exports.ECSqlWriteStatement = exports.ECSqlStatement = exports.ECSqlInsertResult = void 0;
 const core_bentley_1 = require("@itwin/core-bentley");
 const core_geometry_1 = require("@itwin/core-geometry");
 const core_common_1 = require("@itwin/core-common");
@@ -52,6 +52,10 @@ exports.ECSqlInsertResult = ECSqlInsertResult;
  * - [Executing ECSQL]($docs/learning/backend/ExecutingECSQL) provides more background on ECSQL and an introduction on how to execute ECSQL with the iTwin.js API.
  * - [Code Examples]($docs/learning/backend/ECSQLCodeExamples) illustrate the use of the iTwin.js API for executing and working with ECSQL
  * @public
+ * @deprecated in 4.11.  Use [IModelDb.createQueryReader]($backend) or [ECDb.createQueryReader]($backend) to query.
+ * For ECDb, use [ECDb.withCachedWriteStatement]($backend) or [ECDb.withWriteStatement]($backend) to Insert/Update/Delete.
+ * [IModelDb.createQueryReader]($backend) is an asynchronous API. If you encounter a use case that cannot be converted to async, please report an issue at https://github.com/iTwin/itwinjs-core/issues.
+ * Mean while use [IModelDb.withPreparedStatement]($backend) for synchronous API calls where conversion to async is not possible.
  */
 class ECSqlStatement {
     constructor() {
@@ -356,12 +360,216 @@ class ECSqlStatement {
      *
      * See also: [Code Samples]($docs/learning/backend/ECSQLCodeExamples#working-with-the-query-result)
      */
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     getValue(columnIx) {
         (0, core_bentley_1.assert)(undefined !== this._stmt);
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
         return new ECSqlValue(this._stmt.getValue(columnIx));
     }
 }
 exports.ECSqlStatement = ECSqlStatement;
+/** Executes ECSQL INSERT/UPDATE/DELETE statements.
+ *
+ * A statement must be prepared before it can be executed, and it must be released when no longer needed.
+ * See [ECDb.withCachedWriteStatement]($backend) for a convenient and
+ * reliable way to prepare, execute, and then release a statement.
+ *
+ * A statement may contain parameters that must be filled in before use by the **bind** methods.
+ *
+ * Once prepared (and parameters are bound, if any), the statement is executed by calling [ECSqlStatement.stepForInsert]($backend).
+ *
+ * > Preparing a statement can be time-consuming. The best way to reduce the effect of this overhead is to cache and reuse prepared
+ * > statements. A cached prepared statement may be used in different places in an app, as long as the statement is general enough.
+ * > The key to making this strategy work is to phrase a statement in a general way and use placeholders to represent parameters that will vary on each use.
+ *
+ * See also
+ * - [Executing ECSQL]($docs/learning/backend/ExecutingECSQL) provides more background on ECSQL and an introduction on how to execute ECSQL with the iTwin.js API.
+ * - [Code Examples]($docs/learning/backend/ECSQLCodeExamples) illustrate the use of the iTwin.js API for executing and working with ECSQL
+ * @public
+ */
+class ECSqlWriteStatement {
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    constructor(stmt) {
+        if (stmt)
+            this._stmt = stmt;
+        else {
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
+            this._stmt = new ECSqlStatement();
+        }
+    }
+    get sql() { return this._stmt.sql; }
+    /** Check if this statement has been prepared successfully or not */
+    get isPrepared() { return this._stmt.isPrepared; }
+    /** Get the underlying ECSqlStatement.  Needed until we remove ECSqlStatement.
+     * @param
+     * @internal
+     */
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    get stmt() { return this._stmt; }
+    /** Prepare this statement prior to first use.
+     * @param db The ECDb to prepare the statement against
+     * @param ecsql The ECSQL statement string to prepare
+     * @param logErrors Determine if errors are logged or not
+     * @throws [IModelError]($common) if the ECSQL statement cannot be prepared. Normally, prepare fails due to ECSQL syntax errors or references to tables or properties that do not exist.
+     * The error.message property will provide details.
+     * @internal
+     */
+    prepare(db, ecsql, logErrors = true) {
+        this._stmt.prepare(db, ecsql, logErrors);
+    }
+    /** Prepare this statement prior to first use.
+     * @param db The DgnDb or ECDb to prepare the statement against
+     * @param ecsql The ECSQL statement string to prepare
+     * @param logErrors Determine if errors are logged or not, its set to false by default for tryPrepare()
+     * @returns An object with a `status` member equal to [DbResult.BE_SQLITE_OK]($bentley) on success. Upon error, the `message` member will provide details.
+     * @internal
+     */
+    tryPrepare(db, ecsql, logErrors = false) {
+        return this.tryPrepare(db, ecsql, logErrors);
+    }
+    /** Reset this statement so that the next call to step will return the first row, if any. */
+    reset() {
+        this._stmt.reset();
+    }
+    /** Get the Native SQL statement
+     * @internal
+     */
+    getNativeSql() {
+        return this._stmt.getNativeSql();
+    }
+    /** Call this function when finished with this statement. This releases the native resources held by the statement.
+     *
+     * > Do not call this method directly on a statement that is being managed by a statement cache.
+     */
+    dispose() {
+        this._stmt.dispose(); // free native statement
+    }
+    /** Binds the specified value to the specified ECSQL parameter.
+     * The section "[iTwin.js Types used in ECSQL Parameter Bindings]($docs/learning/ECSQLParameterTypes)" describes the
+     * iTwin.js types to be used for the different ECSQL parameter types.
+     * @param parameter Index (1-based) or name of the parameter
+     */
+    bindValue(parameter, val) { this.getBinder(parameter).bind(val); }
+    /** Binds null to the specified ECSQL parameter.
+     * @param parameter Index (1-based) or name of the parameter
+     */
+    bindNull(parameter) { this.getBinder(parameter).bindNull(); }
+    /** Binds a BLOB value to the specified ECSQL parameter.
+     * @param parameter Index (1-based) or name of the parameter
+     * @param BLOB value as either a Uint8Array, ArrayBuffer or a Base64 string
+     */
+    bindBlob(parameter, blob) { this.getBinder(parameter).bindBlob(blob); }
+    /** Binds a boolean value to the specified ECSQL parameter.
+     * @param parameter Index (1-based) or name of the parameter
+     * @param val Boolean value
+     */
+    bindBoolean(parameter, val) { this.getBinder(parameter).bindBoolean(val); }
+    /** Binds a DateTime value to the specified ECSQL parameter.
+     * @param parameter Index (1-based) or name of the parameter
+     * @param isoDateTimeString DateTime value as ISO8601 string
+     */
+    bindDateTime(parameter, isoDateTimeString) { this.getBinder(parameter).bindDateTime(isoDateTimeString); }
+    /** Binds a double value to the specified ECSQL parameter.
+     * @param parameter Index (1-based) or name of the parameter
+     * @param val Double value
+     */
+    bindDouble(parameter, val) { this.getBinder(parameter).bindDouble(val); }
+    /** Binds an GUID value to the specified ECSQL parameter.
+     * @param parameter Index (1-based) or name of the parameter
+     * @param val GUID value
+     */
+    bindGuid(parameter, val) { this.getBinder(parameter).bindGuid(val); }
+    /** Binds an Id value to the specified ECSQL parameter.
+     * @param parameter Index (1-based) or name of the parameter
+     * @param val Id value
+     */
+    bindId(parameter, val) { this.getBinder(parameter).bindId(val); }
+    /** Binds an integer value to the specified ECSQL parameter.
+     * @param parameter Index (1-based) or name of the parameter
+     * @param val Integer value as number, decimal string or hexadecimal string.
+     */
+    bindInteger(parameter, val) { this.getBinder(parameter).bindInteger(val); }
+    /** Binds an Point2d value to the specified ECSQL parameter.
+     * @param parameter Index (1-based) or name of the parameter
+     * @param val Point2d value
+     */
+    bindPoint2d(parameter, val) { this.getBinder(parameter).bindPoint2d(val); }
+    /** Binds an Point3d value to the specified ECSQL parameter.
+     * @param parameter Index (1-based) or name of the parameter
+     * @param val Point3d value
+     */
+    bindPoint3d(parameter, val) { this.getBinder(parameter).bindPoint3d(val); }
+    /** Binds a Range3d as a blob to the specified ECSQL parameter
+     * @param parameter Index(1-based) or name of the parameter
+     * @param val Range3d value
+     */
+    bindRange3d(parameter, val) { this.getBinder(parameter).bindRange3d(val); }
+    /** Binds an string to the specified ECSQL parameter.
+     * @param parameter Index (1-based) or name of the parameter
+     * @param val String value
+     */
+    bindString(parameter, val) { this.getBinder(parameter).bindString(val); }
+    /** Binds a navigation property value to the specified ECSQL parameter.
+     * @param parameter Index (1-based) or name of the parameter
+     * @param val Navigation property value
+     */
+    bindNavigation(parameter, val) { this.getBinder(parameter).bindNavigation(val); }
+    /** Binds a struct property value to the specified ECSQL parameter.
+     * @param parameter Index (1-based) or name of the parameter
+     * @param val Struct value. The struct value is an object composed of pairs of a struct member property name and its value
+     * (of one of the supported types)
+     */
+    bindStruct(parameter, val) { this.getBinder(parameter).bindStruct(val); }
+    /** Binds an array value to the specified ECSQL parameter.
+     * @param parameter Index (1-based) or name of the parameter
+     * @param val Array value. The array value is an array of values of the supported types
+     */
+    bindArray(parameter, val) { this.getBinder(parameter).bindArray(val); }
+    bindIdSet(parameter, val) { this.getBinder(parameter).bindIdSet(val); }
+    /**
+     * Gets a binder to bind a value for an ECSQL parameter
+     * > This is the most low-level API to bind a value to a specific parameter. Alternatively you can use the ECSqlStatement.bindXX methods
+     * > or [ECSqlStatement.bindValues]($backend).
+     * @param parameter Index (1-based) or name of the parameter
+     */
+    getBinder(parameter) {
+        return this._stmt.getBinder(parameter);
+    }
+    /** Bind values to all parameters in the statement.
+     * @param values The values to bind to the parameters.
+     * Pass an *array* of values if the parameters are *positional*.
+     * Pass an *object of the values keyed on the parameter name* for *named parameters*.
+     * The values in either the array or object must match the respective types of the parameter.
+     *
+     * The section "[iTwin.js Types used in ECSQL Parameter Bindings]($docs/learning/ECSQLParameterTypes)" describes the
+     * iTwin.js types to be used for the different ECSQL parameter types.
+     *
+     * See also these [Code Samples]($docs/learning/backend/ECSQLCodeExamples#binding-to-all-parameters-at-once)
+     */
+    bindValues(values) {
+        this._stmt.bindValues(values);
+    }
+    /** Clear any bindings that were previously set on this statement.
+     * @throws [IModelError]($common) in case of errors
+     */
+    clearBindings() {
+        this._stmt.clearBindings();
+    }
+    /** Step this INSERT statement and returns status and the ECInstanceId of the newly
+     * created instance.
+     *
+     * > Insert statements can be used with ECDb only, not with IModelDb.
+     *
+     * @returns Returns the generated ECInstanceId in case of success and the status of the step
+     * call. In case of error, the respective error code is returned.
+     */
+    stepForInsert() {
+        return this._stmt.stepForInsert();
+    }
+    /** Get the query result's column count (only for ECSQL SELECT statements). */
+    getColumnCount() { return this._stmt.getColumnCount(); }
+}
+exports.ECSqlWriteStatement = ECSqlWriteStatement;
 /** Binds a value to an ECSQL parameter.
  *
  * See also:
@@ -522,11 +730,16 @@ exports.ECSqlBinder = ECSqlBinder;
  * - [ECSqlStatement.getValue]($backend)
  * - [Code Samples]($docs/learning/backend/ECSQLCodeExamples#working-with-the-query-result)
  * @public
- */
+ * @deprecated in 4.11.  Use [IModelDb.createQueryReader]($backend) or [ECDb.createQueryReader]($backend) to query.
+ * For ECDb, use [ECDb.withCachedWriteStatement]($backend) or [ECDb.withWriteStatement]($backend) to Insert/Update/Delete.
+ * [IModelDb.createQueryReader]($backend) is an asynchronous API. If you encounter a use case that cannot be converted to async, please report an issue at https://github.com/iTwin/itwinjs-core/issues.
+ * Mean while use [IModelDb.withPreparedStatement]($backend) for synchronous API calls where conversion to async is not possible.
+*/
 class ECSqlValue {
     /** @internal */
     constructor(val) { this._val = val; }
     /** Get information about the query result's column this value refers to. */
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     get columnInfo() { return this._val.getColumnInfo(); }
     /** Get the value of this ECSQL value */
     get value() { return ECSqlValueHelper.getValue(this); }
@@ -571,14 +784,17 @@ class ECSqlValue {
      *  @return ECEnumeration value(s) or undefined if the ECSqlValue does not represent an ECEnumeration.
      *  or is not a strict match of an ECEnumerator or a combination of them.
      */
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     getEnum() { return this._val.getEnum(); }
     /** Get the value as [NavigationValue]($common) */
     getNavigation() { return this._val.getNavigation(); }
     /** Get an iterator for iterating the struct members of this struct value. */
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     getStructIterator() { return new ECSqlValueIterator(this._val.getStructIterator()); }
     /** Get this struct value's content as object literal */
     getStruct() { return ECSqlValueHelper.getStruct(this); }
     /** Get an iterator for iterating the array elements of this array value. */
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     getArrayIterator() { return new ECSqlValueIterator(this._val.getArrayIterator()); }
     /** Get this array value as JavaScript array */
     getArray() { return ECSqlValueHelper.getArray(this); }
@@ -587,15 +803,23 @@ exports.ECSqlValue = ECSqlValue;
 /** Iterator over members of a struct [ECSqlValue]($backend) or the elements of an array [ECSqlValue]($backend).
  * See [ECSqlValue.getStructIterator]($backend) or [ECSqlValue.getArrayIterator]($backend).
  * @public
- */
+ * @deprecated in 4.11.  Use [IModelDb.createQueryReader]($backend) or [ECDb.createQueryReader]($backend) to query.
+ * For ECDb, use [ECDb.withCachedWriteStatement]($backend) or [ECDb.withWriteStatement]($backend) to Insert/Update/Delete.
+ * [IModelDb.createQueryReader]($backend) is an asynchronous API. If you encounter a use case that cannot be converted to async, please report an issue at https://github.com/iTwin/itwinjs-core/issues.
+ * Mean while use [IModelDb.withPreparedStatement]($backend) for synchronous API calls where conversion to async is not possible.
+*/
 class ECSqlValueIterator {
     /** @internal */
     constructor(it) { this._it = it; }
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     next() {
-        if (this._it.moveNext())
+        if (this._it.moveNext()) {
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             return { done: false, value: new ECSqlValue(this._it.getCurrent()) };
+        }
         return { done: true, value: undefined };
     }
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     [Symbol.iterator]() { return this; }
 }
 exports.ECSqlValueIterator = ECSqlValueIterator;
@@ -706,6 +930,7 @@ class ECSqlBindingHelper {
     }
 }
 class ECSqlValueHelper {
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     static getValue(ecsqlValue) {
         if (ecsqlValue.isNull)
             return undefined;
@@ -722,6 +947,7 @@ class ECSqlValueHelper {
                 return ECSqlValueHelper.getPrimitiveValue(ecsqlValue);
         }
     }
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     static getStruct(ecsqlValue) {
         if (ecsqlValue.isNull)
             return undefined;
@@ -740,6 +966,7 @@ class ECSqlValueHelper {
         }
         return structVal;
     }
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     static getArray(ecsqlValue) {
         const arrayVal = [];
         const it = ecsqlValue.getArrayIterator();
@@ -753,9 +980,11 @@ class ECSqlValueHelper {
         }
         return arrayVal;
     }
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     static getPrimitiveValue(ecsqlValue) {
         if (ecsqlValue.isNull)
             return undefined;
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
         const colInfo = ecsqlValue.columnInfo;
         switch (colInfo.getType()) {
             case core_common_1.ECSqlValueType.Blob:
@@ -791,7 +1020,10 @@ class ECSqlValueHelper {
     static queryClassName(ecdb, classId, tableSpace) {
         if (!tableSpace)
             tableSpace = "main";
-        return ecdb.withPreparedStatement(`SELECT s.Name, c.Name FROM [${tableSpace}].meta.ECSchemaDef s, JOIN [${tableSpace}].meta.ECClassDef c ON s.ECInstanceId=c.SchemaId WHERE c.ECInstanceId=?`, (stmt) => {
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
+        return ecdb.withPreparedStatement(`SELECT s.Name, c.Name FROM [${tableSpace}].meta.ECSchemaDef s, JOIN [${tableSpace}].meta.ECClassDef c ON s.ECInstanceId=c.SchemaId WHERE c.ECInstanceId=?`, 
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
+        (stmt) => {
             stmt.bindId(1, classId);
             if (stmt.step() !== core_bentley_1.DbResult.BE_SQLITE_ROW)
                 throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, `No class found with ECClassId ${classId} in table space ${tableSpace}.`);