@itwin/core-backend 5.15.0 → 5.16.0-dev.10

package/lib/cjs/ECSqlRowExecutor.js

@@ -4,193 +4,171 @@
 * See LICENSE.md in the project root for license terms and full copyright notice.
 *--------------------------------------------------------------------------------------------*/
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ECSqlRowExecutor = void 0;
-exports.releaseECSqlStatement = releaseECSqlStatement;
+exports.ECSqlRowExecutor = exports.SyncReaderRowFlags = void 0;
 const core_common_1 = require("@itwin/core-common");
 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.
+/** Column metadata keyed by native statement id and row options. Statement ids change whenever the native cache
+ * prepares the ECSql again, so entries never outlive the statement they describe.
+ */
+const maxCachedMetadataEntries = 100;
+/** Rows fetched by the first native batch. Small so single-row and early-exit queries do little extra work. */
+const initialBatchSize = 4;
+/** Each subsequent batch grows by this factor up to [[maxBatchSize]]. */
+const batchGrowthFactor = 4;
+/** Upper bound on rows rendered per native call; bounds memory held by the read-ahead buffer. */
+const maxBatchSize = 128;
+/** Number of distinct row-flag combinations; metadata keys pack the statement id and the row flags into one number. */
+const rowFlagCombinations = 16;
+const metadataCache = new WeakMap();
+/** Receives the first batch and statement id from `prepareECSqlBatchReader`. Read immediately after each call. */
+const prepareOut = [];
+/** Row rendering flags passed to `prepareECSqlBatchReader`.
  * @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;
+var SyncReaderRowFlags;
+(function (SyncReaderRowFlags) {
+    SyncReaderRowFlags[SyncReaderRowFlags["None"] = 0] = "None";
+    SyncReaderRowFlags[SyncReaderRowFlags["AbbreviateBlobs"] = 1] = "AbbreviateBlobs";
+    SyncReaderRowFlags[SyncReaderRowFlags["ClassIdsToClassNames"] = 2] = "ClassIdsToClassNames";
+    SyncReaderRowFlags[SyncReaderRowFlags["UseJsName"] = 4] = "UseJsName";
+    SyncReaderRowFlags[SyncReaderRowFlags["DoNotConvertClassIdsToClassNamesWhenAliased"] = 8] = "DoNotConvertClassIdsToClassNamesWhenAliased";
+})(SyncReaderRowFlags || (exports.SyncReaderRowFlags = SyncReaderRowFlags = {}));
+function getCachedMetadata(db, key, fetch) {
+    let entries = metadataCache.get(db);
+    if (!entries) {
+        entries = new Map();
+        metadataCache.set(db, entries);
     }
-    try {
-        cache.addOrDispose(stmt);
+    let properties = entries.get(key);
+    if (properties) {
+        entries.delete(key);
     }
-    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);
+    else {
+        properties = fetch();
+        if (entries.size >= maxCachedMetadataEntries)
+            entries.delete(entries.keys().next().value);
     }
+    entries.set(key, properties);
+    return properties;
 }
 // --------------------------------------------------------------------------------------------
 // ECSqlRowExecutor
 // --------------------------------------------------------------------------------------------
 /**
- * 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.
+ * Executes an ECSql query on the db's primary connection and hands out rows one at a time. On a read-only db, rows are
+ * read from native code in growing batches to reduce JS/native transitions; on a writable db native code returns one row
+ * per call so rows are never read ahead of writes made while iterating. The prepared statement is leased from the native
+ * concurrent query statement cache and returned to it when the executor is disposed.
  * @internal
  */
 class ECSqlRowExecutor {
     _db;
-    _stmt;
-    _loggerCategory;
     _removeListener;
-    _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) {
+    _reader;
+    /** Key of this statement's metadata in `metadataCache`, or undefined when its metadata must not be cached. */
+    _metadataKey;
+    _rows = [];
+    _rowIndex = 0;
+    _batchSize = initialBatchSize;
+    /** Status of the last native batch. Anything other than BE_SQLITE_ROW means no further batch is fetched. */
+    _batchStatus = core_bentley_1.DbResult.BE_SQLITE_ROW;
+    constructor(_db) {
         this._db = _db;
-        this._stmt = _stmt;
-        this._loggerCategory = _loggerCategory;
-        this._removeListener = this._db.onBeforeClose.addListener(() => this.cleanup());
+        this._removeListener = this._db.onBeforeClose.addListener(() => this.releaseReader());
     }
     // --------------------------------------------------------------------------------------------
     // Lifecycle
     // --------------------------------------------------------------------------------------------
-    /** 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._isDisposed = true;
-        try {
-            this._stmt[Symbol.dispose]();
-        }
-        catch (error) {
-            logStatementCleanupError(this._loggerCategory, "Failed to dispose an ECSQL statement while closing its database.", error);
-        }
+    /** Returns the leased statement to the native cache. Safe to call more than once. */
+    releaseReader() {
+        const reader = this._reader;
+        this._reader = undefined;
+        this.resetBatch();
+        reader?.dispose();
+    }
+    resetBatch() {
+        this._rows = [];
+        this._rowIndex = 0;
+        this._batchSize = initialBatchSize;
+        this._batchStatus = core_bentley_1.DbResult.BE_SQLITE_ROW;
     }
-    /** Removes the database-close listener owned by this row executor.
+    /** Returns the leased statement and removes the database-close listener owned by this row executor.
      * @internal
      */
     [Symbol.dispose]() {
-        this._isDisposed = true;
         this._removeListener();
+        this.releaseReader();
     }
     // --------------------------------------------------------------------------------------------
     // Core execution
     // --------------------------------------------------------------------------------------------
-    /** Prepare the statement and bind parameters in one step.
-     * Call once during reader initialization — avoids the per-row `ensureStatementReady` check.
+    /** Prepare the statement and bind parameters in one step. On a read-only db the first batch of rows is read by the
+     * same native call.
      * @param query - The ECSql text to prepare.
-     * @param args - Optional bind parameters.
+     * @param args - Optional bind parameters as flat `[key, type, value, ...]` triples.
+     * @param rowFlags - [[SyncReaderRowFlags]] used for every row and for metadata.
      * @throws IModelError on preparation or binding failure.
      * @internal
      */
-    prepareAndBind(query, args) {
-        const prepResult = this.prepareStmt(query);
-        if (!prepResult.isSuccessful)
-            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, prepResult.message ?? `Failed to prepare statement: ${query}`);
-        if (args) {
-            const bindResult = this.bindValues(args);
-            if (!bindResult.isSuccessful)
-                throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, bindResult.message ?? `Failed to bind values: ${query}`);
+    prepareAndBind(query, args, rowFlags) {
+        this.releaseReader();
+        try {
+            this._reader = this._db[Symbols_1._nativeDb].prepareECSqlBatchReader(query, args, rowFlags, this._batchSize, prepareOut);
         }
+        catch (error) {
+            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, core_bentley_1.BentleyError.getErrorMessage(error));
+        }
+        const firstBatch = prepareOut[0];
+        // Metadata of a dynamic column (e.g. $->prop) changes as the statement is stepped, so it is never cached.
+        this._metadataKey = prepareOut[2] ? undefined : prepareOut[1] * rowFlagCombinations + rowFlags;
+        prepareOut.length = 0;
+        if (firstBatch !== undefined)
+            this.acceptBatch(firstBatch);
     }
-    /** Fast-path: step the cursor once and return row data directly.
-     *
-     * Returns the row data array if a row is available.
-     * Returns `undefined` if the result set is exhausted (DONE).
-     *
-     * This avoids all intermediate object allocations (StepResult, RowDataResult,
-     * DbRuntimeStats, DbQueryResponse) that the general `execute()` path creates per row.
-     *
-     * @param options - Native row-adaptor options (should be cached and reused across rows).
-     * @throws IModelError on step failure or row extraction failure.
-     * @internal
-     */
-    stepNextRow(options) {
-        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;
-        if (stepResult === core_bentley_1.DbResult.BE_SQLITE_DONE)
-            return undefined;
-        throw new core_common_1.IModelError(stepResult, `Step failed with code ${stepResult}`);
+    /** Store a batch returned by native code: a JSON array string, an array of rows, or the final DbResult. */
+    acceptBatch(batch) {
+        this._batchSize = Math.min(this._batchSize * batchGrowthFactor, maxBatchSize);
+        this._rowIndex = 0;
+        if (typeof batch === "number") {
+            this._rows = [];
+            this._batchStatus = batch;
+        }
+        else {
+            this._rows = typeof batch === "string" ? JSON.parse(batch) : batch;
+        }
     }
-    /** Get column metadata directly from the prepared statement.
-     * Call once after `prepareAndBind` — the metadata does not change between rows.
-     * @param options - Native row-adaptor options that influence property naming.
-     * @returns Column metadata owned by the caller.
+    /** Return the next row data array, or `undefined` when the result set is exhausted. Rows are served from the
+     * read-ahead buffer; a new native batch is fetched only when the buffer is empty.
+     * @throws IModelError on step failure or when the statement is no longer available. A failure reported by a batch is
+     * thrown after the rows stepped before it have been returned.
      * @internal
      */
-    fetchMetadata(options) {
-        if (this._isDisposed || !this._stmt.isPrepared)
+    stepNextRow() {
+        if (this._rowIndex < this._rows.length)
+            return this._rows[this._rowIndex++];
+        const reader = this._reader;
+        if (!reader)
             throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, statementNotPreparedMessage);
-        return this._stmt.getMetadata(options);
-    }
-    // --------------------------------------------------------------------------------------------
-    // Execution phases
-    // --------------------------------------------------------------------------------------------
-    /** 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 };
+        if (this._batchStatus === core_bentley_1.DbResult.BE_SQLITE_ROW) {
+            this.acceptBatch(reader.stepBatch(this._batchSize));
+            if (this._rows.length > 0)
+                return this._rows[this._rowIndex++];
         }
+        if (this._batchStatus === core_bentley_1.DbResult.BE_SQLITE_DONE)
+            return undefined;
+        throw new core_common_1.IModelError(this._batchStatus, `Step failed with code ${this._batchStatus}`);
     }
-    /** 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.
+    /** Get shared internal column metadata. Readers must copy it before exposing mutable metadata to callers.
      * @internal
      */
-    bindValues(args) {
-        try {
-            if (args === undefined)
-                return { isSuccessful: true };
-            if (!this._stmt.isPrepared)
-                return { isSuccessful: false, message: statementNotPreparedMessage };
-            this._stmt.bindParams(args);
-            return { isSuccessful: true };
-        }
-        catch (error) {
-            return { isSuccessful: false, message: error.message };
-        }
+    fetchMetadata() {
+        const reader = this._reader;
+        if (!reader)
+            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, statementNotPreparedMessage);
+        const fetch = () => new core_common_1.PropertyMetaDataMap(reader.getMetadata());
+        return this._metadataKey === undefined ? fetch() : getCachedMetadata(this._db, this._metadataKey, fetch);
     }
 }
 exports.ECSqlRowExecutor = ECSqlRowExecutor;

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, PropertyMetaDataMap } from \"@itwin/core-common\";\r\nimport type { IModelDb } from \"./IModelDb\";\r\nimport { ECSqlStatement } from \"./ECSqlStatement\";\r\nimport { BentleyError, DbResult, Logger } from \"@itwin/core-bentley\";\r\nimport { IModelJsNative } from \"@bentley/imodeljs-native\";\r\nimport { _nativeDb } from \"./internal/Symbols\";\r\nimport type { ECDb } from \"./ECDb\";\r\nimport type { StatementCache } from \"./SqliteStatement\";\r\n\r\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.\";\r\n\r\nfunction logStatementCleanupError(loggerCategory: string, message: string, error: unknown): void {\r\n  try {\r\n    Logger.logTrace(loggerCategory, message, () => ({ error: BentleyError.getErrorMessage(error) }));\r\n  } catch {\r\n    // Cleanup diagnostics must not replace the original query error.\r\n  }\r\n}\r\n\r\n/** Returns a statement to its cache, falling back to direct disposal without throwing.\r\n * @internal\r\n */\r\n// eslint-disable-next-line @typescript-eslint/no-deprecated\r\nexport function releaseECSqlStatement(stmt: ECSqlStatement, cache: StatementCache<ECSqlStatement>, loggerCategory: string, canCache: boolean): void {\r\n  if (!canCache || !stmt.isPrepared) {\r\n    try {\r\n      stmt[Symbol.dispose]();\r\n    } catch (error) {\r\n      logStatementCleanupError(loggerCategory, \"Failed to dispose an ECSQL statement that could not be cached.\", error);\r\n    }\r\n    return;\r\n  }\r\n\r\n  try {\r\n    cache.addOrDispose(stmt);\r\n  } catch (error) {\r\n    try {\r\n      stmt[Symbol.dispose]();\r\n    } catch (disposeError) {\r\n      logStatementCleanupError(loggerCategory, \"Failed to dispose an ECSQL statement after it could not be returned to the statement cache.\", disposeError);\r\n    }\r\n    logStatementCleanupError(loggerCategory, \"Failed to return an ECSQL statement to the statement cache; attempted direct disposal instead.\", error);\r\n  }\r\n}\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  private _removeListener: () => void;\r\n  private _isDisposed = false;\r\n  private _canCacheStatement = true;\r\n\r\n  /** Whether the statement completed preparation and can be returned to its cache.\r\n   * @internal\r\n   */\r\n  public get canCacheStatement(): boolean { return this._canCacheStatement; }\r\n\r\n  // eslint-disable-next-line @typescript-eslint/no-deprecated\r\n  public constructor(private readonly _db: IModelDb | ECDb, private readonly _stmt: ECSqlStatement, private readonly _loggerCategory: string) {\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 currently held statement without returning it to the cache.\r\n   * Invoked when the db signals it is closing (the statement cache is cleared on close, so the\r\n   * checked-out statement must be disposed directly to avoid a use-after-free or double dispose).\r\n   * @internal\r\n   */\r\n  private cleanup(): void {\r\n    this._isDisposed = true;\r\n    try {\r\n      this._stmt[Symbol.dispose]();\r\n    } catch (error) {\r\n      logStatementCleanupError(this._loggerCategory, \"Failed to dispose an ECSQL statement while closing its database.\", error);\r\n    }\r\n  }\r\n\r\n  /** Removes the database-close listener owned by this row executor.\r\n   * @internal\r\n   */\r\n  public [Symbol.dispose](): void {\r\n    this._isDisposed = true;\r\n    this._removeListener();\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._isDisposed || !this._stmt.isPrepared)\r\n      throw new IModelError(DbResult.BE_SQLITE_ERROR, statementNotPreparedMessage);\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 Column metadata owned by the caller.\r\n   * @internal\r\n   */\r\n  public fetchMetadata(options: IModelJsNative.ECSqlRowAdaptorOptions): PropertyMetaDataMap {\r\n    if (this._isDisposed || !this._stmt.isPrepared)\r\n      throw new IModelError(DbResult.BE_SQLITE_ERROR, statementNotPreparedMessage);\r\n    return this._stmt.getMetadata(options);\r\n  }\r\n\r\n  // --------------------------------------------------------------------------------------------\r\n  // Execution phases\r\n  // --------------------------------------------------------------------------------------------\r\n\r\n  /** Prepares the ECSql statement when the caller did not supply one from its cache.\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    if (this._stmt.isPrepared)\r\n      return { isSuccessful: true };\r\n\r\n    try {\r\n      this._stmt.prepare(this._db[_nativeDb], ecsql);\r\n      return { isSuccessful: true };\r\n    } catch (error: any) {\r\n      this._canCacheStatement = false;\r\n      try {\r\n        this._stmt[Symbol.dispose]();\r\n      } catch (disposeError) {\r\n        logStatementCleanupError(this._loggerCategory, \"Failed to dispose an ECSQL statement after preparation failed.\", disposeError);\r\n      }\r\n      return { isSuccessful: false, message: error.message };\r\n    }\r\n  }\r\n\r\n  /** Binds the supplied parameter values to the prepared statement.\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      if (!this._stmt.isPrepared)\r\n        return { isSuccessful: false, message: statementNotPreparedMessage };\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":["/*---------------------------------------------------------------------------------------------\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, PropertyMetaDataMap } from \"@itwin/core-common\";\r\nimport type { IModelDb } from \"./IModelDb\";\r\nimport { BentleyError, DbResult } from \"@itwin/core-bentley\";\r\nimport { IModelJsNative } from \"@bentley/imodeljs-native\";\r\nimport { _nativeDb } from \"./internal/Symbols\";\r\nimport type { ECDb } from \"./ECDb\";\r\n\r\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.\";\r\n\r\n/** Column metadata keyed by native statement id and row options. Statement ids change whenever the native cache\r\n * prepares the ECSql again, so entries never outlive the statement they describe.\r\n */\r\nconst maxCachedMetadataEntries = 100;\r\n\r\n/** Rows fetched by the first native batch. Small so single-row and early-exit queries do little extra work. */\r\nconst initialBatchSize = 4;\r\n/** Each subsequent batch grows by this factor up to [[maxBatchSize]]. */\r\nconst batchGrowthFactor = 4;\r\n/** Upper bound on rows rendered per native call; bounds memory held by the read-ahead buffer. */\r\nconst maxBatchSize = 128;\r\n/** Number of distinct row-flag combinations; metadata keys pack the statement id and the row flags into one number. */\r\nconst rowFlagCombinations = 16;\r\nconst metadataCache = new WeakMap<IModelDb | ECDb, Map<number, PropertyMetaDataMap>>();\r\n/** Receives the first batch and statement id from `prepareECSqlBatchReader`. Read immediately after each call. */\r\nconst prepareOut: any[] = [];\r\n\r\n/** Row rendering flags passed to `prepareECSqlBatchReader`.\r\n * @internal\r\n */\r\nexport enum SyncReaderRowFlags {\r\n  None = 0,\r\n  AbbreviateBlobs = 1,\r\n  ClassIdsToClassNames = 2,\r\n  UseJsName = 4,\r\n  DoNotConvertClassIdsToClassNamesWhenAliased = 8,\r\n}\r\n\r\nfunction getCachedMetadata(db: IModelDb | ECDb, key: number, fetch: () => PropertyMetaDataMap): PropertyMetaDataMap {\r\n  let entries = metadataCache.get(db);\r\n  if (!entries) {\r\n    entries = new Map();\r\n    metadataCache.set(db, entries);\r\n  }\r\n\r\n  let properties = entries.get(key);\r\n  if (properties) {\r\n    entries.delete(key);\r\n  } else {\r\n    properties = fetch();\r\n    if (entries.size >= maxCachedMetadataEntries)\r\n      entries.delete(entries.keys().next().value as number);\r\n  }\r\n  entries.set(key, properties);\r\n  return properties;\r\n}\r\n\r\n// --------------------------------------------------------------------------------------------\r\n// ECSqlRowExecutor\r\n// --------------------------------------------------------------------------------------------\r\n\r\n/**\r\n * Executes an ECSql query on the db's primary connection and hands out rows one at a time. On a read-only db, rows are\r\n * read from native code in growing batches to reduce JS/native transitions; on a writable db native code returns one row\r\n * per call so rows are never read ahead of writes made while iterating. The prepared statement is leased from the native\r\n * concurrent query statement cache and returned to it when the executor is disposed.\r\n * @internal\r\n */\r\nexport class ECSqlRowExecutor implements Disposable {\r\n  private _removeListener: () => void;\r\n  private _reader?: IModelJsNative.ECSqlBatchReader;\r\n  /** Key of this statement's metadata in `metadataCache`, or undefined when its metadata must not be cached. */\r\n  private _metadataKey: number | undefined;\r\n  private _rows: any[] = [];\r\n  private _rowIndex = 0;\r\n  private _batchSize = initialBatchSize;\r\n  /** Status of the last native batch. Anything other than BE_SQLITE_ROW means no further batch is fetched. */\r\n  private _batchStatus = DbResult.BE_SQLITE_ROW;\r\n\r\n  public constructor(private readonly _db: IModelDb | ECDb) {\r\n    this._removeListener = this._db.onBeforeClose.addListener(() => this.releaseReader());\r\n  }\r\n\r\n  // --------------------------------------------------------------------------------------------\r\n  // Lifecycle\r\n  // --------------------------------------------------------------------------------------------\r\n\r\n  /** Returns the leased statement to the native cache. Safe to call more than once. */\r\n  private releaseReader(): void {\r\n    const reader = this._reader;\r\n    this._reader = undefined;\r\n    this.resetBatch();\r\n    reader?.dispose();\r\n  }\r\n\r\n  private resetBatch(): void {\r\n    this._rows = [];\r\n    this._rowIndex = 0;\r\n    this._batchSize = initialBatchSize;\r\n    this._batchStatus = DbResult.BE_SQLITE_ROW;\r\n  }\r\n\r\n  /** Returns the leased statement and removes the database-close listener owned by this row executor.\r\n   * @internal\r\n   */\r\n  public [Symbol.dispose](): void {\r\n    this._removeListener();\r\n    this.releaseReader();\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. On a read-only db the first batch of rows is read by the\r\n   * same native call.\r\n   * @param query - The ECSql text to prepare.\r\n   * @param args - Optional bind parameters as flat `[key, type, value, ...]` triples.\r\n   * @param rowFlags - [[SyncReaderRowFlags]] used for every row and for metadata.\r\n   * @throws IModelError on preparation or binding failure.\r\n   * @internal\r\n   */\r\n  public prepareAndBind(query: string, args: any[] | undefined, rowFlags: SyncReaderRowFlags): void {\r\n    this.releaseReader();\r\n    try {\r\n      this._reader = this._db[_nativeDb].prepareECSqlBatchReader(query, args, rowFlags, this._batchSize, prepareOut);\r\n    } catch (error) {\r\n      throw new IModelError(DbResult.BE_SQLITE_ERROR, BentleyError.getErrorMessage(error));\r\n    }\r\n    const firstBatch = prepareOut[0];\r\n    // Metadata of a dynamic column (e.g. $->prop) changes as the statement is stepped, so it is never cached.\r\n    this._metadataKey = prepareOut[2] ? undefined : prepareOut[1] * rowFlagCombinations + rowFlags;\r\n    prepareOut.length = 0;\r\n    if (firstBatch !== undefined)\r\n      this.acceptBatch(firstBatch);\r\n  }\r\n\r\n  /** Store a batch returned by native code: a JSON array string, an array of rows, or the final DbResult. */\r\n  private acceptBatch(batch: string | any[] | DbResult): void {\r\n    this._batchSize = Math.min(this._batchSize * batchGrowthFactor, maxBatchSize);\r\n    this._rowIndex = 0;\r\n    if (typeof batch === \"number\") {\r\n      this._rows = [];\r\n      this._batchStatus = batch;\r\n    } else {\r\n      this._rows = typeof batch === \"string\" ? JSON.parse(batch) : batch;\r\n    }\r\n  }\r\n\r\n  /** Return the next row data array, or `undefined` when the result set is exhausted. Rows are served from the\r\n   * read-ahead buffer; a new native batch is fetched only when the buffer is empty.\r\n   * @throws IModelError on step failure or when the statement is no longer available. A failure reported by a batch is\r\n   * thrown after the rows stepped before it have been returned.\r\n   * @internal\r\n   */\r\n  public stepNextRow(): any {\r\n    if (this._rowIndex < this._rows.length)\r\n      return this._rows[this._rowIndex++];\r\n\r\n    const reader = this._reader;\r\n    if (!reader)\r\n      throw new IModelError(DbResult.BE_SQLITE_ERROR, statementNotPreparedMessage);\r\n\r\n    if (this._batchStatus === DbResult.BE_SQLITE_ROW) {\r\n      this.acceptBatch(reader.stepBatch(this._batchSize));\r\n      if (this._rows.length > 0)\r\n        return this._rows[this._rowIndex++];\r\n    }\r\n\r\n    if (this._batchStatus === DbResult.BE_SQLITE_DONE)\r\n      return undefined;\r\n    throw new IModelError(this._batchStatus, `Step failed with code ${this._batchStatus}`);\r\n  }\r\n\r\n  /** Get shared internal column metadata. Readers must copy it before exposing mutable metadata to callers.\r\n   * @internal\r\n   */\r\n  public fetchMetadata(): PropertyMetaDataMap {\r\n    const reader = this._reader;\r\n    if (!reader)\r\n      throw new IModelError(DbResult.BE_SQLITE_ERROR, statementNotPreparedMessage);\r\n    const fetch = () => new PropertyMetaDataMap(reader.getMetadata());\r\n    return this._metadataKey === undefined ? fetch() : getCachedMetadata(this._db, this._metadataKey, fetch);\r\n  }\r\n}\r\n"]}

package/lib/cjs/ECSqlSyncReader.d.ts

@@ -9,8 +9,7 @@ export type SynchronousQueryOptions = Omit<QueryOptions, "suppressLogErrors" | "
  * Execute ECSQL statements synchronously and read the results one row at a time.
  *
  * This is the synchronous counterpart of [[ECSqlReader]] from `@itwin/core-common`.
- * It uses [[ECSqlRowExecutor]] directly — each call to [[step]] fetches exactly one row
- * with no internal caching, paging, or offset tracking.
+ * It uses [[ECSqlRowExecutor]] directly, with read-ahead batches on read-only dbs and live stepping on writable dbs.
  *
  * The query results are returned one row at a time. The format of the row is dictated by the
  * `rowFormat` specified in the `options` parameter of the constructed ECSqlSyncReader object.
@@ -30,12 +29,16 @@ export declare class ECSqlSyncReader extends ECSqlReaderBase implements Iterable
     readonly query: string;
     private _currentRow;
     private _options;
-    /** Cached native row-adaptor options — built once and reused for every row. */
-    private _cachedRowOptions;
+    private _ownsMetadata;
     /**
      * @internal
      */
     constructor(_executor: ECSqlRowExecutor, query: string, param?: QueryBinder, options?: SynchronousQueryOptions);
+    /** Flatten the bindings of `param` into `[key, type, value, ...]` triples, the form read by native code without
+     * per-property lookups. Entries lacking a type or value are skipped, as the object form skipped them.
+     * @internal
+     */
+    private static flattenArgs;
     /**
      * @internal
      */
@@ -44,11 +47,17 @@ export declare class ECSqlSyncReader extends ECSqlReaderBase implements Iterable
      * Reads a single row from the executor. Returns the row data or `undefined` when the
      * result set is exhausted.
      *
-     * Uses the fast-path `stepNextRow` method on the executor, which calls `stmt.step()`
-     * and `stmt.toRow()` directly — no intermediate request/response objects are allocated per row.
+     * Uses the fast-path `stepNextRow` method on the executor, which serves rows from a read-ahead buffer filled by
+     * native code in batches — no intermediate request/response objects are allocated per row.
      * @internal
      */
     private readRow;
+    /**
+     * Native rows parsed from JSON hold `null` for null cells and base64 strings for blobs. Convert them in place to
+     * `undefined` and `Uint8Array`, matching rows whose cells were created directly.
+     * @internal
+     */
+    private static normalizeRow;
     /**
      * Steps the cursor with retry logic for transient busy/interrupt conditions.
      * Returns the row data array, or `undefined` when the result set is exhausted.
@@ -66,11 +75,15 @@ export declare class ECSqlSyncReader extends ECSqlReaderBase implements Iterable
      * @beta
      */
     getMetaData(): QueryPropertyMetaData[];
+    /** Copy shared metadata only when it leaves the reader, including through the row proxy.
+     * @internal
+     */
+    protected getMetaDataInternal(): QueryPropertyMetaData[];
     /**
      * Step to the next row of the query result.
      *
-     * Each call executes exactly one step on the underlying statement — there is no
-     * internal row caching or offset tracking.
+     * On a writable db each step reads the next row from the underlying statement, so changes made inside the callback
+     * are visible to later steps. On a read-only db rows are read ahead in small, growing batches.
      *
      * @returns `true` if a row can be read from `current`.<br/>
      *          `false` if there are no more rows; i.e., all rows have been stepped through already.

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

@@ -1 +1 @@
-{"version":3,"file":"ECSqlSyncReader.d.ts","sourceRoot":"","sources":["../../src/ECSqlSyncReader.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,OAAO,EAEL,eAAe,EAEf,WAAW,EAAE,YAAY,EAAuB,qBAAqB,EAAkB,aAAa,EACrG,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtD,YAAY;AACZ,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,YAAY,EAAE,mBAAmB,GAAG,iBAAiB,GAAG,OAAO,GAAG,UAAU,GAAG,cAAc,GAAG,OAAO,GAAG,gBAAgB,GAAG,OAAO,CAAC,CAAC;AAEjL;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,eAAgB,SAAQ,eAAgB,YAAW,gBAAgB,CAAC,aAAa,CAAC;IAS1E,OAAO,CAAC,SAAS;aAAoC,KAAK,EAAE,MAAM;IARrF,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,QAAQ,CAA0B;IAC1C,+EAA+E;IAC/E,OAAO,CAAC,iBAAiB,CAAM;IAE/B;;OAEG;gBACwB,SAAS,EAAE,gBAAgB,EAAkB,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,uBAAuB;IA+B7I;;OAEG;cACgB,cAAc,IAAI,GAAG,EAAE;IAM1C;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO;IAaf;;;;OAIG;IACH,OAAO,CAAC,aAAa;IASrB;;;;;;;;;OASG;IACI,WAAW,IAAI,qBAAqB,EAAE;IAO7C;;;;;;;;;OASG;IACI,IAAI,IAAI,OAAO;IAYtB;;;;;OAKG;IACI,OAAO,IAAI,GAAG,EAAE;IAQvB;;;;;OAKG;IACI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,aAAa,CAAC;IAI3D;;;;;;;OAOG;IACI,IAAI,IAAI,cAAc,CAAC,aAAa,EAAE,GAAG,CAAC;CAalD"}
+{"version":3,"file":"ECSqlSyncReader.d.ts","sourceRoot":"","sources":["../../src/ECSqlSyncReader.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,OAAO,EAEL,eAAe,EAGf,WAAW,EAAE,YAAY,EAAuB,qBAAqB,EAAkB,aAAa,EACrG,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAAsB,MAAM,oBAAoB,CAAC;AAG1E,YAAY;AACZ,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,YAAY,EAAE,mBAAmB,GAAG,iBAAiB,GAAG,OAAO,GAAG,UAAU,GAAG,cAAc,GAAG,OAAO,GAAG,gBAAgB,GAAG,OAAO,CAAC,CAAC;AAEjL;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,eAAgB,SAAQ,eAAgB,YAAW,gBAAgB,CAAC,aAAa,CAAC;IAQ1E,OAAO,CAAC,SAAS;aAAoC,KAAK,EAAE,MAAM;IAPrF,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,aAAa,CAAS;IAE9B;;OAEG;gBACwB,SAAS,EAAE,gBAAgB,EAAkB,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,uBAAuB;IA4B7I;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAW1B;;OAEG;cACgB,cAAc,IAAI,GAAG,EAAE;IAM1C;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO;IAcf;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAc3B;;;;OAIG;IACH,OAAO,CAAC,aAAa;IASrB;;;;;;;;;OASG;IACI,WAAW,IAAI,qBAAqB,EAAE;IAQ7C;;OAEG;cACgB,mBAAmB,IAAI,qBAAqB,EAAE;IAQjE;;;;;;;;;OASG;IACI,IAAI,IAAI,OAAO;IAYtB;;;;;OAKG;IACI,OAAO,IAAI,GAAG,EAAE;IAQvB;;;;;OAKG;IACI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,aAAa,CAAC;IAI3D;;;;;;;OAOG;IACI,IAAI,IAAI,cAAc,CAAC,aAAa,EAAE,GAAG,CAAC;CAalD"}

package/lib/cjs/ECSqlSyncReader.js

@@ -9,13 +9,13 @@ exports.ECSqlSyncReader = void 0;
  * @module ECSQL
  */
 const core_common_1 = require("@itwin/core-common");
+const ECSqlRowExecutor_1 = require("./ECSqlRowExecutor");
 const core_bentley_1 = require("@itwin/core-bentley");
 /**
  * Execute ECSQL statements synchronously and read the results one row at a time.
  *
  * This is the synchronous counterpart of [[ECSqlReader]] from `@itwin/core-common`.
- * It uses [[ECSqlRowExecutor]] directly — each call to [[step]] fetches exactly one row
- * with no internal caching, paging, or offset tracking.
+ * It uses [[ECSqlRowExecutor]] directly, with read-ahead batches on read-only dbs and live stepping on writable dbs.
  *
  * The query results are returned one row at a time. The format of the row is dictated by the
  * `rowFormat` specified in the `options` parameter of the constructed ECSqlSyncReader object.
@@ -35,8 +35,7 @@ class ECSqlSyncReader extends core_common_1.ECSqlReaderBase {
     query;
     _currentRow;
     _options;
-    /** Cached native row-adaptor options — built once and reused for every row. */
-    _cachedRowOptions;
+    _ownsMetadata = false;
     /**
      * @internal
      */
@@ -51,22 +50,33 @@ class ECSqlSyncReader extends core_common_1.ECSqlReaderBase {
             throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "expecting non-empty ecsql statement");
         }
         this._options = resolvedOptions;
-        const serializedParam = param ? param.serialize() : new core_common_1.QueryBinder().serialize();
-        // Prepare the statement and bind parameters once — avoids per-row ensureStatementReady overhead.
-        const args = Object.keys(serializedParam).length > 0 ? serializedParam : undefined;
-        this._executor.prepareAndBind(this.query, args);
-        // Build and cache the native row-adaptor options — reused for every step call.
+        // Row options are passed to native code once, as flags, and used for every row.
+        let rowFlags = ECSqlRowExecutor_1.SyncReaderRowFlags.DoNotConvertClassIdsToClassNamesWhenAliased;
+        if (this._options.abbreviateBlobs)
+            rowFlags |= ECSqlRowExecutor_1.SyncReaderRowFlags.AbbreviateBlobs;
         // eslint-disable-next-line @typescript-eslint/no-deprecated
-        const valueFormat = this._options.rowFormat === core_common_1.QueryRowFormat.UseJsPropertyNames ? core_common_1.DbValueFormat.JsNames : core_common_1.DbValueFormat.ECSqlNames;
-        this._cachedRowOptions = {
-            abbreviateBlobs: this._options.abbreviateBlobs ?? false,
-            // eslint-disable-next-line @typescript-eslint/no-deprecated
-            classIdsToClassNames: this._options.convertClassIdsToClassNames ?? false,
-            useJsName: valueFormat === core_common_1.DbValueFormat.JsNames,
-            doNotConvertClassIdsToClassNamesWhenAliased: true,
-        };
+        if (this._options.convertClassIdsToClassNames)
+            rowFlags |= ECSqlRowExecutor_1.SyncReaderRowFlags.ClassIdsToClassNames;
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
+        if (this._options.rowFormat === core_common_1.QueryRowFormat.UseJsPropertyNames)
+            rowFlags |= ECSqlRowExecutor_1.SyncReaderRowFlags.UseJsName;
+        this._executor.prepareAndBind(this.query, param ? ECSqlSyncReader.flattenArgs(param) : undefined, rowFlags);
         this._currentRow = undefined;
     }
+    /** Flatten the bindings of `param` into `[key, type, value, ...]` triples, the form read by native code without
+     * per-property lookups. Entries lacking a type or value are skipped, as the object form skipped them.
+     * @internal
+     */
+    static flattenArgs(param) {
+        const serialized = param.serialize();
+        let args;
+        for (const key of Object.keys(serialized)) {
+            const arg = serialized[key];
+            if (typeof arg === "object" && arg !== null && "type" in arg && "value" in arg)
+                (args ??= []).push(key, arg.type, arg.value);
+        }
+        return args;
+    }
     /**
      * @internal
      */
@@ -79,8 +89,8 @@ class ECSqlSyncReader extends core_common_1.ECSqlReaderBase {
      * Reads a single row from the executor. Returns the row data or `undefined` when the
      * result set is exhausted.
      *
-     * Uses the fast-path `stepNextRow` method on the executor, which calls `stmt.step()`
-     * and `stmt.toRow()` directly — no intermediate request/response objects are allocated per row.
+     * Uses the fast-path `stepNextRow` method on the executor, which serves rows from a read-ahead buffer filled by
+     * native code in batches — no intermediate request/response objects are allocated per row.
      * @internal
      */
     readRow() {
@@ -89,19 +99,40 @@ class ECSqlSyncReader extends core_common_1.ECSqlReaderBase {
         }
         // Fetch metadata once on the first call.
         if (this._props.length === 0) {
-            this._props = this._executor.fetchMetadata(this._cachedRowOptions);
+            this._props = this._executor.fetchMetadata();
+            this._ownsMetadata = false;
         }
         return this.stepWithRetry();
     }
+    /**
+     * Native rows parsed from JSON hold `null` for null cells and base64 strings for blobs. Convert them in place to
+     * `undefined` and `Uint8Array`, matching rows whose cells were created directly.
+     * @internal
+     */
+    static normalizeRow(row) {
+        for (let i = 0; i < row.length; ++i) {
+            const val = row[i];
+            if (val === null) {
+                row[i] = undefined;
+            }
+            else if (typeof val === "string") {
+                if (core_common_1.Base64EncodedString.hasPrefix(val))
+                    row[i] = core_common_1.Base64EncodedString.toUint8Array(val);
+            }
+            else if (typeof val === "object" && !(val instanceof Uint8Array)) {
+                ECSqlSyncReader.replaceBase64WithUint8Array(val);
+            }
+        }
+    }
     /**
      * Steps the cursor with retry logic for transient busy/interrupt conditions.
      * Returns the row data array, or `undefined` when the result set is exhausted.
      * @internal
      */
     stepWithRetry() {
-        const result = this._executor.stepNextRow(this._cachedRowOptions);
+        const result = this._executor.stepNextRow();
         if (result) {
-            ECSqlSyncReader.replaceBase64WithUint8Array(result);
+            ECSqlSyncReader.normalizeRow(result);
             return result;
         }
         return undefined; // undefined (done) → undefined
@@ -118,15 +149,26 @@ class ECSqlSyncReader extends core_common_1.ECSqlReaderBase {
      */
     getMetaData() {
         if (this._props.length === 0) {
-            this._props = this._executor.fetchMetadata(this._cachedRowOptions);
+            this._props = this._executor.fetchMetadata();
+            this._ownsMetadata = false;
+        }
+        return this.getMetaDataInternal();
+    }
+    /** Copy shared metadata only when it leaves the reader, including through the row proxy.
+     * @internal
+     */
+    getMetaDataInternal() {
+        if (!this._ownsMetadata) {
+            this._props = new core_common_1.PropertyMetaDataMap(this._props.properties.map((property) => ({ ...property })));
+            this._ownsMetadata = true;
         }
         return this._props.properties;
     }
     /**
      * Step to the next row of the query result.
      *
-     * Each call executes exactly one step on the underlying statement — there is no
-     * internal row caching or offset tracking.
+     * On a writable db each step reads the next row from the underlying statement, so changes made inside the callback
+     * are visible to later steps. On a read-only db rows are read ahead in small, growing batches.
      *
      * @returns `true` if a row can be read from `current`.<br/>
      *          `false` if there are no more rows; i.e., all rows have been stepped through already.