@itwin/core-backend 5.0.0-dev.97 → 5.0.0-dev.99

package/lib/esm/ECSqlStatement.js

@@ -50,6 +50,8 @@ export class 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.
  */
 export class ECSqlStatement {
     _stmt;
@@ -358,11 +360,209 @@ export 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) {
         assert(undefined !== this._stmt);
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
         return new ECSqlValue(this._stmt.getValue(columnIx));
     }
 }
+/** 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
+ */
+export class ECSqlWriteStatement {
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    _stmt;
+    // 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();
+    }
+    /** 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(); }
+}
 /** Binds a value to an ECSQL parameter.
  *
  * See also:
@@ -523,12 +723,14 @@ export class 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) instead.
+*/
 export class ECSqlValue {
     _val;
     /** @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); }
@@ -573,14 +775,17 @@ export 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); }
@@ -588,16 +793,21 @@ export class 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) instead.
+*/
 export class ECSqlValueIterator {
     _it;
     /** @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; }
 }
 class ECSqlBindingHelper {
@@ -707,6 +917,7 @@ class ECSqlBindingHelper {
     }
 }
 class ECSqlValueHelper {
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     static getValue(ecsqlValue) {
         if (ecsqlValue.isNull)
             return undefined;
@@ -723,6 +934,7 @@ class ECSqlValueHelper {
                 return ECSqlValueHelper.getPrimitiveValue(ecsqlValue);
         }
     }
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     static getStruct(ecsqlValue) {
         if (ecsqlValue.isNull)
             return undefined;
@@ -741,6 +953,7 @@ class ECSqlValueHelper {
         }
         return structVal;
     }
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     static getArray(ecsqlValue) {
         const arrayVal = [];
         const it = ecsqlValue.getArrayIterator();
@@ -754,9 +967,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 ECSqlValueType.Blob:
@@ -792,7 +1007,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() !== DbResult.BE_SQLITE_ROW)
                 throw new IModelError(DbResult.BE_SQLITE_ERROR, `No class found with ECClassId ${classId} in table space ${tableSpace}.`);