@itwin/core-backend 5.12.0-dev.9 → 5.13.0-dev.1

package/lib/cjs/ECSqlRowExecutor.d.ts

@@ -1,7 +1,13 @@
 import { QueryPropertyMetaData } from "@itwin/core-common";
-import { IModelDb } from "./IModelDb";
+import type { IModelDb } from "./IModelDb";
+import { ECSqlStatement } from "./ECSqlStatement";
 import { IModelJsNative } from "@bentley/imodeljs-native";
-import { ECDb } from "./ECDb";
+import type { ECDb } from "./ECDb";
+import type { StatementCache } from "./SqliteStatement";
+/** Returns a statement to its cache, falling back to direct disposal without throwing.
+ * @internal
+ */
+export declare function releaseECSqlStatement(stmt: ECSqlStatement, cache: StatementCache<ECSqlStatement>, loggerCategory: string, canCache: boolean): void;
 /**
  * Executes ECSql queries one row at a time against an IModelDb, maintaining statement state between
  * successive calls so the caller can page through results via offset-based requests.
@@ -9,15 +15,23 @@ import { ECDb } from "./ECDb";
  */
 export declare class ECSqlRowExecutor implements Disposable {
     private readonly _db;
-    private _stmt;
+    private readonly _stmt;
+    private readonly _loggerCategory;
     private _removeListener;
-    constructor(_db: IModelDb | ECDb);
-    /** Disposes the current statement and resets all internal state.
-     * Invoked when the db signals that the executor must be recycled.
+    private _isDisposed;
+    private _canCacheStatement;
+    /** Whether the statement completed preparation and can be returned to its cache.
+     * @internal
+     */
+    get canCacheStatement(): boolean;
+    constructor(_db: IModelDb | ECDb, _stmt: ECSqlStatement, _loggerCategory: string);
+    /** Disposes the currently held statement without returning it to the cache.
+     * Invoked when the db signals it is closing (the statement cache is cleared on close, so the
+     * checked-out statement must be disposed directly to avoid a use-after-free or double dispose).
      * @internal
      */
     private cleanup;
-    /** Call this function to dispose the row executor off.
+    /** Removes the database-close listener owned by this row executor.
      * @internal
      */
     [Symbol.dispose](): void;
@@ -49,14 +63,13 @@ export declare class ECSqlRowExecutor implements Disposable {
      * @internal
      */
     fetchMetadata(options: IModelJsNative.ECSqlRowAdaptorOptions): QueryPropertyMetaData[];
-    /** Prepares the ECSql statement against the native database and records the elapsed preparation time.
+    /** Prepares the ECSql statement when the caller did not supply one from its cache.
      * @param ecsql - The ECSql text to prepare.
      * @returns An `OperationResult` indicating success or failure.
      * @internal
      */
     private prepareStmt;
-    /** Resets the statement and binds the given parameter values. Caches the arguments for later
-     * comparison so that redundant rebinds can be skipped.
+    /** Binds the supplied parameter values to the prepared statement.
      * @param args - The parameter object to bind, or `undefined` when no parameters are needed.
      * @returns An `OperationResult` indicating success or failure.
      * @internal

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

@@ -1 +1 @@
-{"version":3,"file":"ECSqlRowExecutor.d.ts","sourceRoot":"","sources":["../../src/ECSqlRowExecutor.ts"],"names":[],"mappings":"AAKA,OAAO,EAAe,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtC,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAkB9B;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IAK9B,OAAO,CAAC,QAAQ,CAAC,GAAG;IAHvC,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,eAAe,CAAa;gBAEA,GAAG,EAAE,QAAQ,GAAG,IAAI;IAUxD;;;OAGG;IACH,OAAO,CAAC,OAAO;IAIf;;OAEG;IACI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAS/B;;;;;;OAMG;IACI,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAazD;;;;;;;;;;;OAWG;IACI,WAAW,CAAC,OAAO,EAAE,cAAc,CAAC,sBAAsB,GAAG,GAAG;IAWvE;;;;;OAKG;IACI,aAAa,CAAC,OAAO,EAAE,cAAc,CAAC,sBAAsB,GAAG,qBAAqB,EAAE;IAQ7F;;;;OAIG;IACH,OAAO,CAAC,WAAW;IASnB;;;;;OAKG;IACH,OAAO,CAAC,UAAU;CAWnB"}
+{"version":3,"file":"ECSqlRowExecutor.d.ts","sourceRoot":"","sources":["../../src/ECSqlRowExecutor.ts"],"names":[],"mappings":"AAKA,OAAO,EAAe,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAYxD;;GAEG;AAEH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,CAAC,cAAc,CAAC,EAAE,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAoBlJ;AAkBD;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IAW9B,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAmB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAAkB,OAAO,CAAC,QAAQ,CAAC,eAAe;IAVlI,OAAO,CAAC,eAAe,CAAa;IACpC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,kBAAkB,CAAQ;IAElC;;OAEG;IACH,IAAW,iBAAiB,IAAI,OAAO,CAAoC;gBAGvC,GAAG,EAAE,QAAQ,GAAG,IAAI,EAAmB,KAAK,EAAE,cAAc,EAAmB,eAAe,EAAE,MAAM;IAQ1I;;;;OAIG;IACH,OAAO,CAAC,OAAO;IASf;;OAEG;IACI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAS/B;;;;;;OAMG;IACI,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAazD;;;;;;;;;;;OAWG;IACI,WAAW,CAAC,OAAO,EAAE,cAAc,CAAC,sBAAsB,GAAG,GAAG;IAWvE;;;;;OAKG;IACI,aAAa,CAAC,OAAO,EAAE,cAAc,CAAC,sBAAsB,GAAG,qBAAqB,EAAE;IAU7F;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAkBnB;;;;OAIG;IACH,OAAO,CAAC,UAAU;CAcnB"}

package/lib/cjs/ECSqlRowExecutor.js

@@ -5,10 +5,46 @@
 *--------------------------------------------------------------------------------------------*/
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ECSqlRowExecutor = void 0;
+exports.releaseECSqlStatement = releaseECSqlStatement;
 const core_common_1 = require("@itwin/core-common");
-const ECSqlStatement_1 = require("./ECSqlStatement");
 const core_bentley_1 = require("@itwin/core-bentley");
 const Symbols_1 = require("./internal/Symbols");
+const statementNotPreparedMessage = "Statement is not prepared. Likely cause: the db was closed before step is called or the ECSqlSyncReader is used outside the context of the callback passed to withQueryReader.";
+function logStatementCleanupError(loggerCategory, message, error) {
+    try {
+        core_bentley_1.Logger.logTrace(loggerCategory, message, () => ({ error: core_bentley_1.BentleyError.getErrorMessage(error) }));
+    }
+    catch {
+        // Cleanup diagnostics must not replace the original query error.
+    }
+}
+/** Returns a statement to its cache, falling back to direct disposal without throwing.
+ * @internal
+ */
+// eslint-disable-next-line @typescript-eslint/no-deprecated
+function releaseECSqlStatement(stmt, cache, loggerCategory, canCache) {
+    if (!canCache || !stmt.isPrepared) {
+        try {
+            stmt[Symbol.dispose]();
+        }
+        catch (error) {
+            logStatementCleanupError(loggerCategory, "Failed to dispose an ECSQL statement that could not be cached.", error);
+        }
+        return;
+    }
+    try {
+        cache.addOrDispose(stmt);
+    }
+    catch (error) {
+        try {
+            stmt[Symbol.dispose]();
+        }
+        catch (disposeError) {
+            logStatementCleanupError(loggerCategory, "Failed to dispose an ECSQL statement after it could not be returned to the statement cache.", disposeError);
+        }
+        logStatementCleanupError(loggerCategory, "Failed to return an ECSQL statement to the statement cache; attempted direct disposal instead.", error);
+    }
+}
 // --------------------------------------------------------------------------------------------
 // ECSqlRowExecutor
 // --------------------------------------------------------------------------------------------
@@ -19,31 +55,45 @@ const Symbols_1 = require("./internal/Symbols");
  */
 class ECSqlRowExecutor {
     _db;
-    // eslint-disable-next-line @typescript-eslint/no-deprecated
     _stmt;
+    _loggerCategory;
     _removeListener;
-    constructor(_db) {
+    _isDisposed = false;
+    _canCacheStatement = true;
+    /** Whether the statement completed preparation and can be returned to its cache.
+     * @internal
+     */
+    get canCacheStatement() { return this._canCacheStatement; }
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    constructor(_db, _stmt, _loggerCategory) {
         this._db = _db;
-        // eslint-disable-next-line @typescript-eslint/no-deprecated
-        this._stmt = new ECSqlStatement_1.ECSqlStatement();
+        this._stmt = _stmt;
+        this._loggerCategory = _loggerCategory;
         this._removeListener = this._db.onBeforeClose.addListener(() => this.cleanup());
     }
     // --------------------------------------------------------------------------------------------
     // Lifecycle
     // --------------------------------------------------------------------------------------------
-    /** Disposes the current statement and resets all internal state.
-     * Invoked when the db signals that the executor must be recycled.
+    /** Disposes the currently held statement without returning it to the cache.
+     * Invoked when the db signals it is closing (the statement cache is cleared on close, so the
+     * checked-out statement must be disposed directly to avoid a use-after-free or double dispose).
      * @internal
      */
     cleanup() {
-        this._stmt[Symbol.dispose]();
+        this._isDisposed = true;
+        try {
+            this._stmt[Symbol.dispose]();
+        }
+        catch (error) {
+            logStatementCleanupError(this._loggerCategory, "Failed to dispose an ECSQL statement while closing its database.", error);
+        }
     }
-    /** Call this function to dispose the row executor off.
+    /** Removes the database-close listener owned by this row executor.
      * @internal
      */
     [Symbol.dispose]() {
+        this._isDisposed = true;
         this._removeListener();
-        this.cleanup();
     }
     // --------------------------------------------------------------------------------------------
     // Core execution
@@ -78,8 +128,8 @@ class ECSqlRowExecutor {
      * @internal
      */
     stepNextRow(options) {
-        if (!this._stmt.isPrepared)
-            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "Statement is not prepared. Likely cause: the db was closed before step is called or the ECSqlSyncReader is used outside the context of the callback passed to withQueryReader.");
+        if (this._isDisposed || !this._stmt.isPrepared)
+            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, statementNotPreparedMessage);
         const stepResult = this._stmt.step();
         if (stepResult === core_bentley_1.DbResult.BE_SQLITE_ROW)
             return this._stmt.toRow(options).data;
@@ -94,27 +144,37 @@ class ECSqlRowExecutor {
      * @internal
      */
     fetchMetadata(options) {
+        if (this._isDisposed || !this._stmt.isPrepared)
+            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, statementNotPreparedMessage);
         return this._stmt.getMetadata(options).properties;
     }
     // --------------------------------------------------------------------------------------------
     // Execution phases
     // --------------------------------------------------------------------------------------------
-    /** Prepares the ECSql statement against the native database and records the elapsed preparation time.
+    /** Prepares the ECSql statement when the caller did not supply one from its cache.
      * @param ecsql - The ECSql text to prepare.
      * @returns An `OperationResult` indicating success or failure.
      * @internal
      */
     prepareStmt(ecsql) {
+        if (this._stmt.isPrepared)
+            return { isSuccessful: true };
         try {
             this._stmt.prepare(this._db[Symbols_1._nativeDb], ecsql);
             return { isSuccessful: true };
         }
         catch (error) {
+            this._canCacheStatement = false;
+            try {
+                this._stmt[Symbol.dispose]();
+            }
+            catch (disposeError) {
+                logStatementCleanupError(this._loggerCategory, "Failed to dispose an ECSQL statement after preparation failed.", disposeError);
+            }
             return { isSuccessful: false, message: error.message };
         }
     }
-    /** Resets the statement and binds the given parameter values. Caches the arguments for later
-     * comparison so that redundant rebinds can be skipped.
+    /** Binds the supplied parameter values to the prepared statement.
      * @param args - The parameter object to bind, or `undefined` when no parameters are needed.
      * @returns An `OperationResult` indicating success or failure.
      * @internal
@@ -123,6 +183,8 @@ class ECSqlRowExecutor {
         try {
             if (args === undefined)
                 return { isSuccessful: true };
+            if (!this._stmt.isPrepared)
+                return { isSuccessful: false, message: statementNotPreparedMessage };
             this._stmt.bindParams(args);
             return { isSuccessful: true };
         }

package/lib/cjs/ECSqlRowExecutor.js.map

@@ -1 +1 @@
-{"version":3,"file":"ECSqlRowExecutor.js","sourceRoot":"","sources":["../../src/ECSqlRowExecutor.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n\r\nimport { IModelError, QueryPropertyMetaData } from \"@itwin/core-common\";\r\nimport { IModelDb } from \"./IModelDb\";\r\nimport { ECSqlStatement } from \"./ECSqlStatement\";\r\nimport { DbResult } from \"@itwin/core-bentley\";\r\nimport { IModelJsNative } from \"@bentley/imodeljs-native\";\r\nimport { _nativeDb } from \"./internal/Symbols\";\r\nimport { ECDb } from \"./ECDb\";\r\n\r\n// --------------------------------------------------------------------------------------------\r\n// Internal result types\r\n// --------------------------------------------------------------------------------------------\r\n\r\n/** Result of an internal operation that may fail with a message.\r\n * @internal\r\n */\r\ninterface OperationResult {\r\n  isSuccessful: boolean;\r\n  message?: string;\r\n}\r\n\r\n// --------------------------------------------------------------------------------------------\r\n// ECSqlRowExecutor\r\n// --------------------------------------------------------------------------------------------\r\n\r\n/**\r\n * Executes ECSql queries one row at a time against an IModelDb, maintaining statement state between\r\n * successive calls so the caller can page through results via offset-based requests.\r\n * @internal\r\n */\r\nexport class ECSqlRowExecutor implements Disposable {\r\n  // eslint-disable-next-line @typescript-eslint/no-deprecated\r\n  private _stmt: ECSqlStatement;\r\n  private _removeListener: () => void;\r\n\r\n  public constructor(private readonly _db: IModelDb | ECDb) {\r\n    // eslint-disable-next-line @typescript-eslint/no-deprecated\r\n    this._stmt = new ECSqlStatement();\r\n    this._removeListener = this._db.onBeforeClose.addListener(() => this.cleanup());\r\n  }\r\n\r\n  // --------------------------------------------------------------------------------------------\r\n  // Lifecycle\r\n  // --------------------------------------------------------------------------------------------\r\n\r\n  /** Disposes the current statement and resets all internal state.\r\n   * Invoked when the db signals that the executor must be recycled.\r\n   * @internal\r\n   */\r\n  private cleanup(): void {\r\n    this._stmt[Symbol.dispose]();\r\n  }\r\n\r\n  /** Call this function to dispose the row executor off.\r\n   * @internal\r\n   */\r\n  public [Symbol.dispose](): void {\r\n    this._removeListener();\r\n    this.cleanup();\r\n  }\r\n\r\n  // --------------------------------------------------------------------------------------------\r\n  // Core execution\r\n  // --------------------------------------------------------------------------------------------\r\n\r\n  /** Prepare the statement and bind parameters in one step.\r\n   * Call once during reader initialization — avoids the per-row `ensureStatementReady` check.\r\n   * @param query - The ECSql text to prepare.\r\n   * @param args - Optional bind parameters.\r\n   * @throws IModelError on preparation or binding failure.\r\n   * @internal\r\n   */\r\n  public prepareAndBind(query: string, args?: object): void {\r\n\r\n    const prepResult = this.prepareStmt(query);\r\n    if (!prepResult.isSuccessful)\r\n      throw new IModelError(DbResult.BE_SQLITE_ERROR, prepResult.message ?? `Failed to prepare statement: ${query}`);\r\n\r\n    if (args) {\r\n      const bindResult = this.bindValues(args);\r\n      if (!bindResult.isSuccessful)\r\n        throw new IModelError(DbResult.BE_SQLITE_ERROR, bindResult.message ?? `Failed to bind values: ${query}`);\r\n    }\r\n  }\r\n\r\n  /** Fast-path: step the cursor once and return row data directly.\r\n   *\r\n   * Returns the row data array if a row is available.\r\n   * Returns `undefined` if the result set is exhausted (DONE).\r\n   *\r\n   * This avoids all intermediate object allocations (StepResult, RowDataResult,\r\n   * DbRuntimeStats, DbQueryResponse) that the general `execute()` path creates per row.\r\n   *\r\n   * @param options - Native row-adaptor options (should be cached and reused across rows).\r\n   * @throws IModelError on step failure or row extraction failure.\r\n   * @internal\r\n   */\r\n  public stepNextRow(options: IModelJsNative.ECSqlRowAdaptorOptions): any {\r\n    if (!this._stmt.isPrepared)\r\n      throw new IModelError(DbResult.BE_SQLITE_ERROR, \"Statement is not prepared. Likely cause: the db was closed before step is called or the ECSqlSyncReader is used outside the context of the callback passed to withQueryReader.\");\r\n    const stepResult = this._stmt.step();\r\n    if (stepResult === DbResult.BE_SQLITE_ROW)\r\n      return this._stmt.toRow(options).data;\r\n    if (stepResult === DbResult.BE_SQLITE_DONE)\r\n      return undefined;\r\n    throw new IModelError(stepResult, `Step failed with code ${stepResult}`);\r\n  }\r\n\r\n  /** Get column metadata directly from the prepared statement.\r\n   * Call once after `prepareAndBind` — the metadata does not change between rows.\r\n   * @param options - Native row-adaptor options that influence property naming.\r\n   * @returns Array of column metadata.\r\n   * @internal\r\n   */\r\n  public fetchMetadata(options: IModelJsNative.ECSqlRowAdaptorOptions): QueryPropertyMetaData[] {\r\n    return this._stmt.getMetadata(options).properties;\r\n  }\r\n\r\n  // --------------------------------------------------------------------------------------------\r\n  // Execution phases\r\n  // --------------------------------------------------------------------------------------------\r\n\r\n  /** Prepares the ECSql statement against the native database and records the elapsed preparation time.\r\n   * @param ecsql - The ECSql text to prepare.\r\n   * @returns An `OperationResult` indicating success or failure.\r\n   * @internal\r\n   */\r\n  private prepareStmt(ecsql: string): OperationResult {\r\n    try {\r\n      this._stmt.prepare(this._db[_nativeDb], ecsql);\r\n      return { isSuccessful: true };\r\n    } catch (error: any) {\r\n      return { isSuccessful: false, message: error.message };\r\n    }\r\n  }\r\n\r\n  /** Resets the statement and binds the given parameter values. Caches the arguments for later\r\n   * comparison so that redundant rebinds can be skipped.\r\n   * @param args - The parameter object to bind, or `undefined` when no parameters are needed.\r\n   * @returns An `OperationResult` indicating success or failure.\r\n   * @internal\r\n   */\r\n  private bindValues(args: object | undefined): OperationResult {\r\n    try {\r\n      if (args === undefined)\r\n        return { isSuccessful: true };\r\n\r\n      this._stmt.bindParams(args);\r\n      return { isSuccessful: true };\r\n    } catch (error: any) {\r\n      return { isSuccessful: false, message: error.message };\r\n    }\r\n  }\r\n}"]}
+{"version":3,"file":"ECSqlRowExecutor.js","sourceRoot":"","sources":["../../src/ECSqlRowExecutor.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n\nimport { IModelError, QueryPropertyMetaData } from \"@itwin/core-common\";\nimport type { IModelDb } from \"./IModelDb\";\nimport { ECSqlStatement } from \"./ECSqlStatement\";\nimport { BentleyError, DbResult, Logger } from \"@itwin/core-bentley\";\nimport { IModelJsNative } from \"@bentley/imodeljs-native\";\nimport { _nativeDb } from \"./internal/Symbols\";\nimport type { ECDb } from \"./ECDb\";\nimport type { StatementCache } from \"./SqliteStatement\";\n\nconst statementNotPreparedMessage = \"Statement is not prepared. Likely cause: the db was closed before step is called or the ECSqlSyncReader is used outside the context of the callback passed to withQueryReader.\";\n\nfunction logStatementCleanupError(loggerCategory: string, message: string, error: unknown): void {\n  try {\n    Logger.logTrace(loggerCategory, message, () => ({ error: BentleyError.getErrorMessage(error) }));\n  } catch {\n    // Cleanup diagnostics must not replace the original query error.\n  }\n}\n\n/** Returns a statement to its cache, falling back to direct disposal without throwing.\n * @internal\n */\n// eslint-disable-next-line @typescript-eslint/no-deprecated\nexport function releaseECSqlStatement(stmt: ECSqlStatement, cache: StatementCache<ECSqlStatement>, loggerCategory: string, canCache: boolean): void {\n  if (!canCache || !stmt.isPrepared) {\n    try {\n      stmt[Symbol.dispose]();\n    } catch (error) {\n      logStatementCleanupError(loggerCategory, \"Failed to dispose an ECSQL statement that could not be cached.\", error);\n    }\n    return;\n  }\n\n  try {\n    cache.addOrDispose(stmt);\n  } catch (error) {\n    try {\n      stmt[Symbol.dispose]();\n    } catch (disposeError) {\n      logStatementCleanupError(loggerCategory, \"Failed to dispose an ECSQL statement after it could not be returned to the statement cache.\", disposeError);\n    }\n    logStatementCleanupError(loggerCategory, \"Failed to return an ECSQL statement to the statement cache; attempted direct disposal instead.\", error);\n  }\n}\n\n// --------------------------------------------------------------------------------------------\n// Internal result types\n// --------------------------------------------------------------------------------------------\n\n/** Result of an internal operation that may fail with a message.\n * @internal\n */\ninterface OperationResult {\n  isSuccessful: boolean;\n  message?: string;\n}\n\n// --------------------------------------------------------------------------------------------\n// ECSqlRowExecutor\n// --------------------------------------------------------------------------------------------\n\n/**\n * Executes ECSql queries one row at a time against an IModelDb, maintaining statement state between\n * successive calls so the caller can page through results via offset-based requests.\n * @internal\n */\nexport class ECSqlRowExecutor implements Disposable {\n  private _removeListener: () => void;\n  private _isDisposed = false;\n  private _canCacheStatement = true;\n\n  /** Whether the statement completed preparation and can be returned to its cache.\n   * @internal\n   */\n  public get canCacheStatement(): boolean { return this._canCacheStatement; }\n\n  // eslint-disable-next-line @typescript-eslint/no-deprecated\n  public constructor(private readonly _db: IModelDb | ECDb, private readonly _stmt: ECSqlStatement, private readonly _loggerCategory: string) {\n    this._removeListener = this._db.onBeforeClose.addListener(() => this.cleanup());\n  }\n\n  // --------------------------------------------------------------------------------------------\n  // Lifecycle\n  // --------------------------------------------------------------------------------------------\n\n  /** Disposes the currently held statement without returning it to the cache.\n   * Invoked when the db signals it is closing (the statement cache is cleared on close, so the\n   * checked-out statement must be disposed directly to avoid a use-after-free or double dispose).\n   * @internal\n   */\n  private cleanup(): void {\n    this._isDisposed = true;\n    try {\n      this._stmt[Symbol.dispose]();\n    } catch (error) {\n      logStatementCleanupError(this._loggerCategory, \"Failed to dispose an ECSQL statement while closing its database.\", error);\n    }\n  }\n\n  /** Removes the database-close listener owned by this row executor.\n   * @internal\n   */\n  public [Symbol.dispose](): void {\n    this._isDisposed = true;\n    this._removeListener();\n  }\n\n  // --------------------------------------------------------------------------------------------\n  // Core execution\n  // --------------------------------------------------------------------------------------------\n\n  /** Prepare the statement and bind parameters in one step.\n   * Call once during reader initialization — avoids the per-row `ensureStatementReady` check.\n   * @param query - The ECSql text to prepare.\n   * @param args - Optional bind parameters.\n   * @throws IModelError on preparation or binding failure.\n   * @internal\n   */\n  public prepareAndBind(query: string, args?: object): void {\n\n    const prepResult = this.prepareStmt(query);\n    if (!prepResult.isSuccessful)\n      throw new IModelError(DbResult.BE_SQLITE_ERROR, prepResult.message ?? `Failed to prepare statement: ${query}`);\n\n    if (args) {\n      const bindResult = this.bindValues(args);\n      if (!bindResult.isSuccessful)\n        throw new IModelError(DbResult.BE_SQLITE_ERROR, bindResult.message ?? `Failed to bind values: ${query}`);\n    }\n  }\n\n  /** Fast-path: step the cursor once and return row data directly.\n   *\n   * Returns the row data array if a row is available.\n   * Returns `undefined` if the result set is exhausted (DONE).\n   *\n   * This avoids all intermediate object allocations (StepResult, RowDataResult,\n   * DbRuntimeStats, DbQueryResponse) that the general `execute()` path creates per row.\n   *\n   * @param options - Native row-adaptor options (should be cached and reused across rows).\n   * @throws IModelError on step failure or row extraction failure.\n   * @internal\n   */\n  public stepNextRow(options: IModelJsNative.ECSqlRowAdaptorOptions): any {\n    if (this._isDisposed || !this._stmt.isPrepared)\n      throw new IModelError(DbResult.BE_SQLITE_ERROR, statementNotPreparedMessage);\n    const stepResult = this._stmt.step();\n    if (stepResult === DbResult.BE_SQLITE_ROW)\n      return this._stmt.toRow(options).data;\n    if (stepResult === DbResult.BE_SQLITE_DONE)\n      return undefined;\n    throw new IModelError(stepResult, `Step failed with code ${stepResult}`);\n  }\n\n  /** Get column metadata directly from the prepared statement.\n   * Call once after `prepareAndBind` — the metadata does not change between rows.\n   * @param options - Native row-adaptor options that influence property naming.\n   * @returns Array of column metadata.\n   * @internal\n   */\n  public fetchMetadata(options: IModelJsNative.ECSqlRowAdaptorOptions): QueryPropertyMetaData[] {\n    if (this._isDisposed || !this._stmt.isPrepared)\n      throw new IModelError(DbResult.BE_SQLITE_ERROR, statementNotPreparedMessage);\n    return this._stmt.getMetadata(options).properties;\n  }\n\n  // --------------------------------------------------------------------------------------------\n  // Execution phases\n  // --------------------------------------------------------------------------------------------\n\n  /** Prepares the ECSql statement when the caller did not supply one from its cache.\n   * @param ecsql - The ECSql text to prepare.\n   * @returns An `OperationResult` indicating success or failure.\n   * @internal\n   */\n  private prepareStmt(ecsql: string): OperationResult {\n    if (this._stmt.isPrepared)\n      return { isSuccessful: true };\n\n    try {\n      this._stmt.prepare(this._db[_nativeDb], ecsql);\n      return { isSuccessful: true };\n    } catch (error: any) {\n      this._canCacheStatement = false;\n      try {\n        this._stmt[Symbol.dispose]();\n      } catch (disposeError) {\n        logStatementCleanupError(this._loggerCategory, \"Failed to dispose an ECSQL statement after preparation failed.\", disposeError);\n      }\n      return { isSuccessful: false, message: error.message };\n    }\n  }\n\n  /** Binds the supplied parameter values to the prepared statement.\n   * @param args - The parameter object to bind, or `undefined` when no parameters are needed.\n   * @returns An `OperationResult` indicating success or failure.\n   * @internal\n   */\n  private bindValues(args: object | undefined): OperationResult {\n    try {\n      if (args === undefined)\n        return { isSuccessful: true };\n\n      if (!this._stmt.isPrepared)\n        return { isSuccessful: false, message: statementNotPreparedMessage };\n\n      this._stmt.bindParams(args);\n      return { isSuccessful: true };\n    } catch (error: any) {\n      return { isSuccessful: false, message: error.message };\n    }\n  }\n}"]}