@itwin/core-backend 5.14.0-dev.21 → 5.14.0-dev.22

package/lib/esm/IModelDb.js

@@ -615,17 +615,18 @@ export class IModelDb extends IModel {
             throw err;
         }
     }
-    /** Allow to execute query and read results along with meta data. The result are streamed.
+    /** Creates a reader for asynchronous ECSQL query execution.
+     * Execution starts when the reader is consumed using asynchronous iteration or awaited calls to `step()` or `toArray()`.
+     * Results are fetched and buffered in batches. For synchronous, callback-scoped execution, use [[withQueryReader]].
      *
      * See also:
-     * - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
-     * - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
+     * - [Choosing a query reader]($docs/learning/backend/ExecutingECSQL)
+     * - [Asynchronous query examples]($docs/learning/ECSQLCodeExamples)
      * - [ECSQL Row Format]($docs/learning/ECSQLRowFormat)
      *
      * @param params The values to bind to the parameters (if the ECSQL has any).
      * @param config Allow to specify certain flags which control how query is executed.
      * @returns Returns an [ECSqlReader]($common) which helps iterate over the result set and also give access to metadata.
-     * Should be used when we donot want true step by step behaviour and want to take advantage of caching capabilities of the reader.
      * @public
      * */
     createQueryReader(ecsql, params, config) {
@@ -638,20 +639,21 @@ export class IModelDb extends IModel {
         };
         return new ECSqlReader(executor, ecsql, params, config);
     }
-    /** Allow to execute query and read results along with meta data. The result are stepped one by one.
+    /** Executes a callback with a synchronous ECSQL reader on the owning database connection.
+     * The reader steps one row at a time without buffering result batches. Finish using it before the callback completes.
+     * Return materialized rows or computed values rather than the reader. For asynchronous execution, use [[createQueryReader]].
+     * The prepared statement may be reused from the statement cache between completed calls.
      *
      * See also:
-     * - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
-     * - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
+     * - [Choosing a query reader]($docs/learning/backend/ExecutingECSQL)
+     * - [Synchronous query examples]($docs/learning/backend/WithQueryReaderCodeExamples)
      * - [ECSQL Row Format]($docs/learning/ECSQLRowFormat)
      * @param ecsql The ECSQL query to execute.
-     * @param callback the callback to invoke on the prepared ECSqlReader
+     * @param callback the callback to invoke on the prepared ECSqlSyncReader
      * @param params The values to bind to the parameters (if the ECSQL has any).
      * @param config Allow to specify certain flags which control how query is executed.
      * @returns the value returned by `callback`.
      * @throws IModelError if db is not open.
-     * Use this method for true step-by-step row consumption without intermediate result or page caching.
-     * The prepared ECSQL statement may be reused from the statement cache between completed calls.
      * @beta
      * */
     withQueryReader(ecsql, callback, params, config) {
@@ -1413,7 +1415,10 @@ export class IModelDb extends IModel {
                 const result = await reader.next();
                 if (result.done)
                     throw new IModelError(DbResult.BE_SQLITE_ERROR, "PRAGMA checksum(schema_token) returned no rows");
-                return result.value.sha3_256;
+                const token = result.value.sha3_256;
+                if (typeof token !== "string")
+                    throw new IModelError(DbResult.BE_SQLITE_ERROR, "PRAGMA checksum(schema_token) returned an invalid sha3_256 column");
+                return token;
             },
         };
     }
@@ -1432,7 +1437,9 @@ export class IModelDb extends IModel {
         const token = result.value.schemaToken;
         if (data === undefined || data === null)
             throw new IModelError(DbResult.BE_SQLITE_ERROR, `${pragma} returned null data column`);
-        return { data, schemaToken: token ?? "" };
+        if (typeof token !== "string")
+            throw new IModelError(DbResult.BE_SQLITE_ERROR, `${pragma} returned an invalid schemaToken column`);
+        return { data, schemaToken: token };
     }
     /** Get the linkTableRelationships for this IModel */
     get relationships() {