@itwin/core-backend 5.8.0-dev.2 → 5.8.0-dev.20

package/lib/esm/ECSqlSyncReader.js

@@ -0,0 +1,187 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module ECSQL
+ */
+import { DbValueFormat, ECSqlReaderBase, IModelError, PropertyMetaDataMap, QueryBinder, QueryOptionsBuilder, QueryRowFormat, } from "@itwin/core-common";
+import { DbResult } from "@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.
+ *
+ * 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.
+ * Defaults to [[QueryRowFormat.UseECSqlPropertyIndexes]] when no `rowFormat` is defined.
+ *
+ * There are three primary ways to interact with and read the results:
+ * - Iterate using ECSqlSyncReader as a synchronous iterator.
+ * - Step manually using [[ECSqlSyncReader.step]].
+ * - Capture all results at once using [[ECSqlSyncReader.toArray]].
+ *
+ * @note When iterating over the results, the current row is a [[QueryRowProxy]] object.
+ *       To get the row as a basic JavaScript object, call [[QueryRowProxy.toRow]] on it.
+ * @beta
+ */
+export class ECSqlSyncReader extends ECSqlReaderBase {
+    _executor;
+    query;
+    _currentRow;
+    _options;
+    /** Cached native row-adaptor options — built once and reused for every row. */
+    _cachedRowOptions;
+    /**
+     * @internal
+     */
+    constructor(_executor, query, param, options) {
+        const resolvedOptions = options ?? new QueryOptionsBuilder().getOptions();
+        if (typeof resolvedOptions.rowFormat === "undefined")
+            resolvedOptions.rowFormat = QueryRowFormat.UseECSqlPropertyIndexes;
+        super(resolvedOptions.rowFormat);
+        this._executor = _executor;
+        this.query = query;
+        if (query.trim().length === 0) {
+            throw new IModelError(DbResult.BE_SQLITE_ERROR, "expecting non-empty ecsql statement");
+        }
+        this._options = resolvedOptions;
+        const serializedParam = param ? param.serialize() : new 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.
+        const valueFormat = this._options.rowFormat === QueryRowFormat.UseJsPropertyNames ? DbValueFormat.JsNames : DbValueFormat.ECSqlNames;
+        this._cachedRowOptions = {
+            abbreviateBlobs: this._options.abbreviateBlobs ?? false,
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
+            classIdsToClassNames: this._options.convertClassIdsToClassNames ?? false,
+            useJsName: valueFormat === DbValueFormat.JsNames,
+            doNotConvertClassIdsToClassNamesWhenAliased: true,
+        };
+        this._currentRow = undefined;
+    }
+    /**
+     * @internal
+     */
+    getRowInternal() {
+        if (!this._currentRow)
+            throw new IModelError(DbResult.BE_SQLITE_ERROR, "no current row");
+        return this._currentRow;
+    }
+    /**
+     * 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.
+     * @internal
+     */
+    readRow() {
+        if (this._done) {
+            return undefined;
+        }
+        // Fetch metadata once on the first call.
+        if (this._props.length === 0) {
+            this._props = new PropertyMetaDataMap(this._executor.fetchMetadata(this._cachedRowOptions));
+        }
+        return this.stepWithRetry();
+    }
+    /**
+     * 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);
+        if (result) {
+            ECSqlSyncReader.replaceBase64WithUint8Array(result);
+            return result;
+        }
+        return undefined; // undefined (done) → undefined
+    }
+    /**
+     * Get the metadata for each column in the query result.
+     *
+     * If metadata has not been retrieved yet, fetches it directly from the prepared
+     * statement. If a step has not yet occurred, executes a single step to ensure
+     * the statement cursor is positioned, preserving the row for the next [[step]] call.
+     *
+     * @returns An array of [[QueryPropertyMetaData]].
+     * @beta
+     */
+    getMetaData() {
+        if (this._props.length === 0) {
+            this._props = new PropertyMetaDataMap(this._executor.fetchMetadata(this._cachedRowOptions));
+        }
+        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.
+     *
+     * @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.
+     * @beta
+     */
+    step() {
+        if (this._done) {
+            return false;
+        }
+        this._currentRow = this.readRow();
+        if (!this._currentRow) {
+            this._done = true;
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Get all remaining rows from the query result.
+     *
+     * @returns An array of all remaining rows from the query result.
+     * @beta
+     */
+    toArray() {
+        const rows = [];
+        while (this.step()) {
+            rows.push(this.formatCurrentRow());
+        }
+        return rows;
+    }
+    /**
+     * Accessor for using ECSqlSyncReader as a synchronous iterator.
+     *
+     * @returns A synchronous iterator over the rows returned by the executed ECSQL query.
+     * @beta
+     */
+    [Symbol.iterator]() {
+        return this;
+    }
+    /**
+     * Calls step when called as an iterator.
+     *
+     * Returns the row alongside a `done` boolean to indicate if there are any more rows for an iterator to step to.
+     *
+     * @returns An object with the keys: `value` which contains the row and `done` which contains a boolean.
+     * @beta
+     */
+    next() {
+        if (this.step()) {
+            return {
+                done: false,
+                value: this.current,
+            };
+        }
+        else {
+            return {
+                done: true,
+                value: this.current,
+            };
+        }
+    }
+}
+//# sourceMappingURL=ECSqlSyncReader.js.map

package/lib/esm/ECSqlSyncReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ECSqlSyncReader.js","sourceRoot":"","sources":["../../src/ECSqlSyncReader.ts"],"names":[],"mappings":"AAAA;;;+FAG+F;AAC/F;;GAEG;AACH,OAAO,EACL,aAAa,EACb,eAAe,EACf,WAAW,EACX,mBAAmB,EAAE,WAAW,EAAgB,mBAAmB,EAAyB,cAAc,GAC3G,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAK/C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,eAAgB,SAAQ,eAAe;IASvB;IAA6C;IARhE,WAAW,CAAM;IACjB,QAAQ,CAA0B;IAC1C,+EAA+E;IACvE,iBAAiB,CAAM;IAE/B;;OAEG;IACH,YAA2B,SAA2B,EAAkB,KAAa,EAAE,KAAmB,EAAE,OAAiC;QAC3I,MAAM,eAAe,GAAG,OAAO,IAAI,IAAI,mBAAmB,EAAE,CAAC,UAAU,EAAE,CAAC;QAC1E,IAAI,OAAO,eAAe,CAAC,SAAS,KAAK,WAAW;YAClD,eAAe,CAAC,SAAS,GAAG,cAAc,CAAC,uBAAuB,CAAC;QAErE,KAAK,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;QALR,cAAS,GAAT,SAAS,CAAkB;QAAkB,UAAK,GAAL,KAAK,CAAQ;QAOnF,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,WAAW,CAAC,QAAQ,CAAC,eAAe,EAAE,qCAAqC,CAAC,CAAC;QACzF,CAAC;QAED,IAAI,CAAC,QAAQ,GAAG,eAAe,CAAC;QAChC,MAAM,eAAe,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,SAAS,EAAE,CAAC;QAElF,iGAAiG;QACjG,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC;QACnF,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAEhD,+EAA+E;QAC/E,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,KAAK,cAAc,CAAC,kBAAkB,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,UAAU,CAAC;QACrI,IAAI,CAAC,iBAAiB,GAAG;YACvB,eAAe,EAAE,IAAI,CAAC,QAAQ,CAAC,eAAe,IAAI,KAAK;YACvD,4DAA4D;YAC5D,oBAAoB,EAAE,IAAI,CAAC,QAAQ,CAAC,2BAA2B,IAAI,KAAK;YACxE,SAAS,EAAE,WAAW,KAAK,aAAa,CAAC,OAAO;YAChD,2CAA2C,EAAE,IAAI;SAClD,CAAC;QACF,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;IAC/B,CAAC;IAED;;OAEG;IACgB,cAAc;QAC/B,IAAI,CAAC,IAAI,CAAC,WAAW;YACnB,MAAM,IAAI,WAAW,CAAC,QAAQ,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAAC;QACpE,OAAO,IAAI,CAAC,WAAoB,CAAC;IACnC,CAAC;IAED;;;;;;;OAOG;IACK,OAAO;QACb,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,yCAAyC;QACzC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,IAAI,CAAC,MAAM,GAAG,IAAI,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC;QAC9F,CAAC;QAED,OAAO,IAAI,CAAC,aAAa,EAAE,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACK,aAAa;QACnB,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAClE,IAAI,MAAM,EAAE,CAAC;YACX,eAAe,CAAC,2BAA2B,CAAC,MAAM,CAAC,CAAC;YACpD,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,SAAS,CAAC,CAAC,+BAA+B;IACnD,CAAC;IAED;;;;;;;;;OASG;IACI,WAAW;QAChB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,IAAI,CAAC,MAAM,GAAG,IAAI,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC;QAC9F,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC;IAChC,CAAC;IAED;;;;;;;;;OASG;IACI,IAAI;QACT,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAClC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;YAClB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACI,OAAO;QACZ,MAAM,IAAI,GAAG,EAAE,CAAC;QAChB,OAAO,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YACnB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC;QACrC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACI,CAAC,MAAM,CAAC,QAAQ,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;OAOG;IACI,IAAI;QACT,IAAI,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YAChB,OAAO;gBACL,IAAI,EAAE,KAAK;gBACX,KAAK,EAAE,IAAI,CAAC,OAAO;aACpB,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,OAAO;gBACL,IAAI,EAAE,IAAI;gBACV,KAAK,EAAE,IAAI,CAAC,OAAO;aACpB,CAAC;QACJ,CAAC;IACH,CAAC;CACF","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/** @packageDocumentation\n * @module ECSQL\n */\nimport {\n  DbValueFormat,\n  ECSqlReaderBase,\n  IModelError,\n  PropertyMetaDataMap, QueryBinder, QueryOptions, QueryOptionsBuilder, QueryPropertyMetaData, QueryRowFormat, QueryRowProxy,\n} from \"@itwin/core-common\";\nimport { ECSqlRowExecutor } from \"./ECSqlRowExecutor\";\nimport { DbResult } from \"@itwin/core-bentley\";\n\n/** @beta */\nexport type SynchronousQueryOptions = Omit<QueryOptions, \"suppressLogErrors\" | \"includeMetaData\" | \"limit\" | \"priority\" | \"restartToken\" | \"delay\" | \"usePrimaryConn\" | \"quota\">;\n\n/**\n * Execute ECSQL statements synchronously and read the results one row at a time.\n *\n * This is the synchronous counterpart of [[ECSqlReader]] from `@itwin/core-common`.\n * It uses [[ECSqlRowExecutor]] directly — each call to [[step]] fetches exactly one row\n * with no internal caching, paging, or offset tracking.\n *\n * The query results are returned one row at a time. The format of the row is dictated by the\n * `rowFormat` specified in the `options` parameter of the constructed ECSqlSyncReader object.\n * Defaults to [[QueryRowFormat.UseECSqlPropertyIndexes]] when no `rowFormat` is defined.\n *\n * There are three primary ways to interact with and read the results:\n * - Iterate using ECSqlSyncReader as a synchronous iterator.\n * - Step manually using [[ECSqlSyncReader.step]].\n * - Capture all results at once using [[ECSqlSyncReader.toArray]].\n *\n * @note When iterating over the results, the current row is a [[QueryRowProxy]] object.\n *       To get the row as a basic JavaScript object, call [[QueryRowProxy.toRow]] on it.\n * @beta\n */\nexport class ECSqlSyncReader extends ECSqlReaderBase implements IterableIterator<QueryRowProxy> {\n  private _currentRow: any;\n  private _options: SynchronousQueryOptions;\n  /** Cached native row-adaptor options — built once and reused for every row. */\n  private _cachedRowOptions: any;\n\n  /**\n   * @internal\n   */\n  public constructor(private _executor: ECSqlRowExecutor, public readonly query: string, param?: QueryBinder, options?: SynchronousQueryOptions) {\n    const resolvedOptions = options ?? new QueryOptionsBuilder().getOptions();\n    if (typeof resolvedOptions.rowFormat === \"undefined\")\n      resolvedOptions.rowFormat = QueryRowFormat.UseECSqlPropertyIndexes;\n\n    super(resolvedOptions.rowFormat);\n\n    if (query.trim().length === 0) {\n      throw new IModelError(DbResult.BE_SQLITE_ERROR, \"expecting non-empty ecsql statement\");\n    }\n\n    this._options = resolvedOptions;\n    const serializedParam = param ? param.serialize() : new QueryBinder().serialize();\n\n    // Prepare the statement and bind parameters once — avoids per-row ensureStatementReady overhead.\n    const args = Object.keys(serializedParam).length > 0 ? serializedParam : undefined;\n    this._executor.prepareAndBind(this.query, args);\n\n    // Build and cache the native row-adaptor options — reused for every step call.\n    const valueFormat = this._options.rowFormat === QueryRowFormat.UseJsPropertyNames ? DbValueFormat.JsNames : DbValueFormat.ECSqlNames;\n    this._cachedRowOptions = {\n      abbreviateBlobs: this._options.abbreviateBlobs ?? false,\n      // eslint-disable-next-line @typescript-eslint/no-deprecated\n      classIdsToClassNames: this._options.convertClassIdsToClassNames ?? false,\n      useJsName: valueFormat === DbValueFormat.JsNames,\n      doNotConvertClassIdsToClassNamesWhenAliased: true,\n    };\n    this._currentRow = undefined;\n  }\n\n  /**\n   * @internal\n   */\n  protected override getRowInternal(): any[] {\n    if (!this._currentRow)\n      throw new IModelError(DbResult.BE_SQLITE_ERROR, \"no current row\");\n    return this._currentRow as any[];\n  }\n\n  /**\n   * Reads a single row from the executor. Returns the row data or `undefined` when the\n   * result set is exhausted.\n   *\n   * Uses the fast-path `stepNextRow` method on the executor, which calls `stmt.step()`\n   * and `stmt.toRow()` directly — no intermediate request/response objects are allocated per row.\n   * @internal\n   */\n  private readRow(): any {\n    if (this._done) {\n      return undefined;\n    }\n\n    // Fetch metadata once on the first call.\n    if (this._props.length === 0) {\n      this._props = new PropertyMetaDataMap(this._executor.fetchMetadata(this._cachedRowOptions));\n    }\n\n    return this.stepWithRetry();\n  }\n\n  /**\n   * Steps the cursor with retry logic for transient busy/interrupt conditions.\n   * Returns the row data array, or `undefined` when the result set is exhausted.\n   * @internal\n   */\n  private stepWithRetry(): any {\n    const result = this._executor.stepNextRow(this._cachedRowOptions);\n    if (result) {\n      ECSqlSyncReader.replaceBase64WithUint8Array(result);\n      return result;\n    }\n    return undefined; // undefined (done) → undefined\n  }\n\n  /**\n   * Get the metadata for each column in the query result.\n   *\n   * If metadata has not been retrieved yet, fetches it directly from the prepared\n   * statement. If a step has not yet occurred, executes a single step to ensure\n   * the statement cursor is positioned, preserving the row for the next [[step]] call.\n   *\n   * @returns An array of [[QueryPropertyMetaData]].\n   * @beta\n   */\n  public getMetaData(): QueryPropertyMetaData[] {\n    if (this._props.length === 0) {\n      this._props = new PropertyMetaDataMap(this._executor.fetchMetadata(this._cachedRowOptions));\n    }\n    return this._props.properties;\n  }\n\n  /**\n   * Step to the next row of the query result.\n   *\n   * Each call executes exactly one step on the underlying statement — there is no\n   * internal row caching or offset tracking.\n   *\n   * @returns `true` if a row can be read from `current`.<br/>\n   *          `false` if there are no more rows; i.e., all rows have been stepped through already.\n   * @beta\n   */\n  public step(): boolean {\n    if (this._done) {\n      return false;\n    }\n    this._currentRow = this.readRow();\n    if (!this._currentRow) {\n      this._done = true;\n      return false;\n    }\n    return true;\n  }\n\n  /**\n   * Get all remaining rows from the query result.\n   *\n   * @returns An array of all remaining rows from the query result.\n   * @beta\n   */\n  public toArray(): any[] {\n    const rows = [];\n    while (this.step()) {\n      rows.push(this.formatCurrentRow());\n    }\n    return rows;\n  }\n\n  /**\n   * Accessor for using ECSqlSyncReader as a synchronous iterator.\n   *\n   * @returns A synchronous iterator over the rows returned by the executed ECSQL query.\n   * @beta\n   */\n  public [Symbol.iterator](): IterableIterator<QueryRowProxy> {\n    return this;\n  }\n\n  /**\n   * Calls step when called as an iterator.\n   *\n   * Returns the row alongside a `done` boolean to indicate if there are any more rows for an iterator to step to.\n   *\n   * @returns An object with the keys: `value` which contains the row and `done` which contains a boolean.\n   * @beta\n   */\n  public next(): IteratorResult<QueryRowProxy, any> {\n    if (this.step()) {\n      return {\n        done: false,\n        value: this.current,\n      };\n    } else {\n      return {\n        done: true,\n        value: this.current,\n      };\n    }\n  }\n}\n"]}