@itwin/core-backend 3.0.0-dev.100

package/lib/cjs/ECDb.d.ts

@@ -0,0 +1,196 @@
+import { IModelJsNative } from "@bentley/imodeljs-native";
+/** @packageDocumentation
+ * @module ECDb
+ */
+import { IDisposable } from "@itwin/core-bentley";
+import { ECSqlReader, QueryBinder, QueryOptions, QueryRowFormat } from "@itwin/core-common";
+import { ECSqlStatement } from "./ECSqlStatement";
+import { SqliteStatement } from "./SqliteStatement";
+/** Modes for how to open [ECDb]($backend) files.
+ * @public
+ */
+export declare enum ECDbOpenMode {
+    Readonly = 0,
+    ReadWrite = 1,
+    /** Opens the file read-write and upgrades the file if necessary to the latest file format version. */
+    FileUpgrade = 2
+}
+/** An ECDb file
+ * @public
+ */
+export declare class ECDb implements IDisposable {
+    private _nativeDb?;
+    private _concurrentQueryInitialized;
+    private readonly _statementCache;
+    private _sqliteStatementCache;
+    private _concurrentQueryStats;
+    /** only for tests
+     * @internal
+     */
+    resetSqliteCache(size: number): void;
+    constructor();
+    /** Call this function when finished with this ECDb object. This releases the native resources held by the
+     *  ECDb object.
+     */
+    dispose(): void;
+    /** Create an ECDb
+     * @param pathName The path to the ECDb file to create.
+     * @throws [IModelError]($common) if the operation failed.
+     */
+    createDb(pathName: string): void;
+    /** Open the ECDb.
+     * @param pathName The path to the ECDb file to open
+     * @param openMode Open mode
+     * @throws [IModelError]($common) if the operation failed.
+     */
+    openDb(pathName: string, openMode?: ECDbOpenMode): void;
+    /** Returns true if the ECDb is open */
+    get isOpen(): boolean;
+    /** Close the Db after saving any uncommitted changes.
+     * @throws [IModelError]($common) if the database is not open.
+     */
+    closeDb(): void;
+    /** @internal use to test statement caching */
+    clearStatementCache(): void;
+    /** @internal use to test statement caching */
+    getCachedStatementCount(): number;
+    /** Commit the outermost transaction, writing changes to the file. Then, restart the transaction.
+     * @param changesetName The name of the operation that generated these changes.
+     * @throws [IModelError]($common) if the database is not open or if the operation failed.
+     */
+    saveChanges(changesetName?: string): void;
+    /** Abandon (cancel) the outermost transaction, discarding all changes since last save. Then, restart the transaction.
+     * @throws [IModelError]($common) if the database is not open or if the operation failed.
+     */
+    abandonChanges(): void;
+    /** Import a schema.
+     *
+     * If the import was successful, the database is automatically saved to disk.
+     * @param pathName Path to ECSchema XML file to import.
+     * @throws [IModelError]($common) if the database is not open or if the operation failed.
+     */
+    importSchema(pathName: string): void;
+    /**
+     * Use a prepared ECSQL statement, potentially from the statement cache. If the requested statement doesn't exist
+     * in the statement cache, a new statement is prepared. After the callback completes, the statement is reset and saved
+     * in the statement cache so it can be reused in the future. Use this method for ECSQL statements that will be
+     * reused often and are expensive to prepare. The statement cache holds the most recently used statements, discarding
+     * the oldest statements as it fills. For statements you don't intend to reuse, instead use [[withStatement]].
+     * @param sql The SQLite SQL statement to execute
+     * @param callback the callback to invoke on the prepared statement
+     * @param logErrors Determines if error will be logged if statement fail to prepare
+     * @returns the value returned by `callback`.
+     * @see [[withStatement]]
+     * @public
+     */
+    withPreparedStatement<T>(ecsql: string, callback: (stmt: ECSqlStatement) => T, logErrors?: boolean): T;
+    /**
+     * Prepared and execute a callback on an ECSQL statement. After the callback completes the statement is disposed.
+     * Use this method for ECSQL statements are either not expected to be reused, or are not expensive to prepare.
+     * For statements that will be reused often, instead use [[withPreparedStatement]].
+     * @param sql The SQLite SQL statement to execute
+     * @param callback the callback to invoke on the prepared statement
+     * @param logErrors Determines if error will be logged if statement fail to prepare
+     * @returns the value returned by `callback`.
+     * @see [[withPreparedStatement]]
+     * @public
+     */
+    withStatement<T>(ecsql: string, callback: (stmt: ECSqlStatement) => T, logErrors?: boolean): T;
+    /** Prepare an ECSQL statement.
+     * @param ecsql The ECSQL statement to prepare
+     * @param logErrors Determines if error will be logged if statement fail to prepare
+     * @throws [IModelError]($common) if there is a problem preparing the statement.
+     */
+    prepareStatement(ecsql: string, logErrors?: boolean): ECSqlStatement;
+    /**
+     * Use a prepared SQL statement, potentially from the statement cache. If the requested statement doesn't exist
+     * in the statement cache, a new statement is prepared. After the callback completes, the statement is reset and saved
+     * in the statement cache so it can be reused in the future. Use this method for SQL statements that will be
+     * reused often and are expensive to prepare. The statement cache holds the most recently used statements, discarding
+     * the oldest statements as it fills. For statements you don't intend to reuse, instead use [[withSqliteStatement]].
+     * @param sql The SQLite SQL statement to execute
+     * @param callback the callback to invoke on the prepared statement
+     * @param logErrors Determines if error will be logged if statement fail to prepare
+     * @returns the value returned by `callback`.
+     * @see [[withPreparedStatement]]
+     * @public
+     */
+    withPreparedSqliteStatement<T>(sql: string, callback: (stmt: SqliteStatement) => T, logErrors?: boolean): T;
+    /**
+     * Prepared and execute a callback on a SQL statement. After the callback completes the statement is disposed.
+     * Use this method for SQL statements are either not expected to be reused, or are not expensive to prepare.
+     * For statements that will be reused often, instead use [[withPreparedSqliteStatement]].
+     * @param sql The SQLite SQL statement to execute
+     * @param callback the callback to invoke on the prepared statement
+     * @param logErrors Determines if error will be logged if statement fail to prepare
+     * @returns the value returned by `callback`.
+     * @public
+     */
+    withSqliteStatement<T>(sql: string, callback: (stmt: SqliteStatement) => T, logErrors?: boolean): T;
+    /** Prepare an SQL statement.
+     * @param sql The SQLite SQL statement to prepare
+     * @param logErrors Determines if error will be logged if statement fail to prepare
+     * @throws [IModelError]($common) if there is a problem preparing the statement.
+     * @internal
+     */
+    prepareSqliteStatement(sql: string, logErrors?: boolean): SqliteStatement;
+    /** @internal */
+    get nativeDb(): IModelJsNative.ECDb;
+    /** Allow to execute query and read results along with meta data. The result are streamed.
+     * @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 *ECSqlQueryReader* which help iterate over result set and also give access to meta data.
+     * @beta
+     * */
+    createQueryReader(ecsql: string, params?: QueryBinder, config?: QueryOptions): ECSqlReader;
+    /** Execute a query and stream its results
+     * The result of the query is async iterator over the rows. The iterator will get next page automatically once rows in current page has been read.
+     * [ECSQL row]($docs/learning/ECSQLRowFormat).
+     *
+     * See also:
+     * - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
+     * - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
+     *
+     * @param ecsql The ECSQL statement to execute
+     * @param params The values to bind to the parameters (if the ECSQL has any).
+     * @param rowFormat Specify what format the row will be returned. It default to Array format though to make it compilable with previous version use *QueryRowFormat.UseJsPropertyNames*
+     * @param options Allow to specify certain flags which control how query is executed.
+     * @returns Returns the query result as an *AsyncIterableIterator<any>*  which lazy load result as needed. The row format is determined by *rowFormat* parameter.
+     * See [ECSQL row format]($docs/learning/ECSQLRowFormat) for details about the format of the returned rows.
+     * @throws [IModelError]($common) If there was any error while submitting, preparing or stepping into query
+     */
+    query(ecsql: string, params?: QueryBinder, rowFormat?: QueryRowFormat, options?: QueryOptions): AsyncIterableIterator<any>;
+    /** Compute number of rows that would be returned by the ECSQL.
+     *
+     * See also:
+     * - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
+     * - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
+     *
+     * @param ecsql The ECSQL statement to execute
+     * @param params The values to bind to the parameters (if the ECSQL has any).
+     * See "[iModel.js Types used in ECSQL Parameter Bindings]($docs/learning/ECSQLParameterTypes)" for details.
+     * @returns Return row count.
+     * @throws [IModelError]($common) If the statement is invalid
+     */
+    queryRowCount(ecsql: string, params?: QueryBinder): Promise<number>;
+    /** Cancel any previous query with same token and run execute the current specified query.
+     * The result of the query is async iterator over the rows. The iterator will get next page automatically once rows in current page has been read.
+     * [ECSQL row]($docs/learning/ECSQLRowFormat).
+     *
+     * See also:
+     * - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
+     * - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
+     *
+     * @param ecsql The ECSQL statement to execute
+     * @param token None empty restart token. The previous query with same token would be cancelled. This would cause
+     * exception which user code must handle.
+     * @param params The values to bind to the parameters (if the ECSQL has any).
+     * @param rowFormat Specify what format the row will be returned. It default to Array format though to make it compilable with previous version use *QueryRowFormat.UseJsPropertyNames*
+     * @param options Allow to specify certain flags which control how query is executed.
+     * @returns Returns the query result as an *AsyncIterableIterator<any>*  which lazy load result as needed. The row format is determined by *rowFormat* parameter.
+     * See [ECSQL row format]($docs/learning/ECSQLRowFormat) for details about the format of the returned rows.
+     * @throws [IModelError]($common) If there was any error while submitting, preparing or stepping into query
+     */
+    restartQuery(token: string, ecsql: string, params?: QueryBinder, rowFormat?: QueryRowFormat, options?: QueryOptions): AsyncIterableIterator<any>;
+}
+//# sourceMappingURL=ECDb.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ECDb.d.ts","sourceRoot":"","sources":["../../src/ECDb.ts"],"names":[],"mappings":"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"}

package/lib/cjs/ECDb.js

@@ -0,0 +1,354 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ECDb = exports.ECDbOpenMode = void 0;
+/** @packageDocumentation
+ * @module ECDb
+ */
+const core_bentley_1 = require("@itwin/core-bentley");
+const core_common_1 = require("@itwin/core-common");
+const BackendLoggerCategory_1 = require("./BackendLoggerCategory");
+const ConcurrentQuery_1 = require("./ConcurrentQuery");
+const ECSqlStatement_1 = require("./ECSqlStatement");
+const IModelHost_1 = require("./IModelHost");
+const SqliteStatement_1 = require("./SqliteStatement");
+const loggerCategory = BackendLoggerCategory_1.BackendLoggerCategory.ECDb;
+/** Modes for how to open [ECDb]($backend) files.
+ * @public
+ */
+var ECDbOpenMode;
+(function (ECDbOpenMode) {
+    ECDbOpenMode[ECDbOpenMode["Readonly"] = 0] = "Readonly";
+    ECDbOpenMode[ECDbOpenMode["ReadWrite"] = 1] = "ReadWrite";
+    /** Opens the file read-write and upgrades the file if necessary to the latest file format version. */
+    ECDbOpenMode[ECDbOpenMode["FileUpgrade"] = 2] = "FileUpgrade";
+})(ECDbOpenMode = exports.ECDbOpenMode || (exports.ECDbOpenMode = {}));
+/** An ECDb file
+ * @public
+ */
+class ECDb {
+    constructor() {
+        this._concurrentQueryInitialized = false;
+        this._statementCache = new SqliteStatement_1.StatementCache();
+        this._sqliteStatementCache = new SqliteStatement_1.StatementCache();
+        this._concurrentQueryStats = { resetTimerHandle: null, logTimerHandle: null, lastActivityTime: Date.now(), dispose: () => { } };
+        this._nativeDb = new IModelHost_1.IModelHost.platform.ECDb();
+    }
+    /** only for tests
+     * @internal
+     */
+    resetSqliteCache(size) {
+        this._sqliteStatementCache.clear();
+        this._sqliteStatementCache = new SqliteStatement_1.StatementCache(size);
+    }
+    /** Call this function when finished with this ECDb object. This releases the native resources held by the
+     *  ECDb object.
+     */
+    dispose() {
+        if (!this._nativeDb)
+            return;
+        this.closeDb();
+        this._nativeDb.dispose();
+        this._nativeDb = undefined;
+    }
+    /** Create an ECDb
+     * @param pathName The path to the ECDb file to create.
+     * @throws [IModelError]($common) if the operation failed.
+     */
+    createDb(pathName) {
+        const status = this.nativeDb.createDb(pathName);
+        if (status !== core_bentley_1.DbResult.BE_SQLITE_OK)
+            throw new core_common_1.IModelError(status, "Failed to created ECDb");
+    }
+    /** Open the ECDb.
+     * @param pathName The path to the ECDb file to open
+     * @param openMode Open mode
+     * @throws [IModelError]($common) if the operation failed.
+     */
+    openDb(pathName, openMode = ECDbOpenMode.Readonly) {
+        const nativeOpenMode = openMode === ECDbOpenMode.Readonly ? core_bentley_1.OpenMode.Readonly : core_bentley_1.OpenMode.ReadWrite;
+        const tryUpgrade = openMode === ECDbOpenMode.FileUpgrade;
+        const status = this.nativeDb.openDb(pathName, nativeOpenMode, tryUpgrade);
+        if (status !== core_bentley_1.DbResult.BE_SQLITE_OK)
+            throw new core_common_1.IModelError(status, "Failed to open ECDb");
+    }
+    /** Returns true if the ECDb is open */
+    get isOpen() { return this.nativeDb.isOpen(); }
+    /** Close the Db after saving any uncommitted changes.
+     * @throws [IModelError]($common) if the database is not open.
+     */
+    closeDb() {
+        this._statementCache.clear();
+        this._sqliteStatementCache.clear();
+        this.nativeDb.closeDb();
+        this._concurrentQueryStats.dispose();
+    }
+    /** @internal use to test statement caching */
+    clearStatementCache() {
+        this._statementCache.clear();
+    }
+    /** @internal use to test statement caching */
+    getCachedStatementCount() {
+        return this._statementCache.size;
+    }
+    /** Commit the outermost transaction, writing changes to the file. Then, restart the transaction.
+     * @param changesetName The name of the operation that generated these changes.
+     * @throws [IModelError]($common) if the database is not open or if the operation failed.
+     */
+    saveChanges(changesetName) {
+        const status = this.nativeDb.saveChanges(changesetName);
+        if (status !== core_bentley_1.DbResult.BE_SQLITE_OK)
+            throw new core_common_1.IModelError(status, "Failed to save changes");
+    }
+    /** Abandon (cancel) the outermost transaction, discarding all changes since last save. Then, restart the transaction.
+     * @throws [IModelError]($common) if the database is not open or if the operation failed.
+     */
+    abandonChanges() {
+        const status = this.nativeDb.abandonChanges();
+        if (status !== core_bentley_1.DbResult.BE_SQLITE_OK)
+            throw new core_common_1.IModelError(status, "Failed to abandon changes");
+    }
+    /** Import a schema.
+     *
+     * If the import was successful, the database is automatically saved to disk.
+     * @param pathName Path to ECSchema XML file to import.
+     * @throws [IModelError]($common) if the database is not open or if the operation failed.
+     */
+    importSchema(pathName) {
+        const status = this.nativeDb.importSchema(pathName);
+        if (status !== core_bentley_1.DbResult.BE_SQLITE_OK) {
+            core_bentley_1.Logger.logError(loggerCategory, `Failed to import schema from '${pathName}'.`);
+            throw new core_common_1.IModelError(status, `Failed to import schema from '${pathName}'.`);
+        }
+    }
+    /**
+     * Use a prepared ECSQL statement, potentially from the statement cache. If the requested statement doesn't exist
+     * in the statement cache, a new statement is prepared. After the callback completes, the statement is reset and saved
+     * in the statement cache so it can be reused in the future. Use this method for ECSQL statements that will be
+     * reused often and are expensive to prepare. The statement cache holds the most recently used statements, discarding
+     * the oldest statements as it fills. For statements you don't intend to reuse, instead use [[withStatement]].
+     * @param sql The SQLite SQL statement to execute
+     * @param callback the callback to invoke on the prepared statement
+     * @param logErrors Determines if error will be logged if statement fail to prepare
+     * @returns the value returned by `callback`.
+     * @see [[withStatement]]
+     * @public
+     */
+    withPreparedStatement(ecsql, callback, logErrors = true) {
+        var _a;
+        const stmt = (_a = this._statementCache.findAndRemove(ecsql)) !== null && _a !== void 0 ? _a : this.prepareStatement(ecsql, logErrors);
+        const release = () => this._statementCache.addOrDispose(stmt);
+        try {
+            const val = callback(stmt);
+            if (val instanceof Promise) {
+                val.then(release, release);
+            }
+            else {
+                release();
+            }
+            return val;
+        }
+        catch (err) {
+            release();
+            throw err;
+        }
+    }
+    /**
+     * Prepared and execute a callback on an ECSQL statement. After the callback completes the statement is disposed.
+     * Use this method for ECSQL statements are either not expected to be reused, or are not expensive to prepare.
+     * For statements that will be reused often, instead use [[withPreparedStatement]].
+     * @param sql The SQLite SQL statement to execute
+     * @param callback the callback to invoke on the prepared statement
+     * @param logErrors Determines if error will be logged if statement fail to prepare
+     * @returns the value returned by `callback`.
+     * @see [[withPreparedStatement]]
+     * @public
+     */
+    withStatement(ecsql, callback, logErrors = true) {
+        const stmt = this.prepareStatement(ecsql, logErrors);
+        const release = () => stmt.dispose();
+        try {
+            const val = callback(stmt);
+            if (val instanceof Promise) {
+                val.then(release, release);
+            }
+            else {
+                release();
+            }
+            return val;
+        }
+        catch (err) {
+            release();
+            throw err;
+        }
+    }
+    /** Prepare an ECSQL statement.
+     * @param ecsql The ECSQL statement to prepare
+     * @param logErrors Determines if error will be logged if statement fail to prepare
+     * @throws [IModelError]($common) if there is a problem preparing the statement.
+     */
+    prepareStatement(ecsql, logErrors = true) {
+        const stmt = new ECSqlStatement_1.ECSqlStatement();
+        stmt.prepare(this.nativeDb, ecsql, logErrors);
+        return stmt;
+    }
+    /**
+     * Use a prepared SQL statement, potentially from the statement cache. If the requested statement doesn't exist
+     * in the statement cache, a new statement is prepared. After the callback completes, the statement is reset and saved
+     * in the statement cache so it can be reused in the future. Use this method for SQL statements that will be
+     * reused often and are expensive to prepare. The statement cache holds the most recently used statements, discarding
+     * the oldest statements as it fills. For statements you don't intend to reuse, instead use [[withSqliteStatement]].
+     * @param sql The SQLite SQL statement to execute
+     * @param callback the callback to invoke on the prepared statement
+     * @param logErrors Determines if error will be logged if statement fail to prepare
+     * @returns the value returned by `callback`.
+     * @see [[withPreparedStatement]]
+     * @public
+     */
+    withPreparedSqliteStatement(sql, callback, logErrors = true) {
+        var _a;
+        const stmt = (_a = this._sqliteStatementCache.findAndRemove(sql)) !== null && _a !== void 0 ? _a : this.prepareSqliteStatement(sql, logErrors);
+        const release = () => this._sqliteStatementCache.addOrDispose(stmt);
+        try {
+            const val = callback(stmt);
+            if (val instanceof Promise) {
+                val.then(release, release);
+            }
+            else {
+                release();
+            }
+            return val;
+        }
+        catch (err) {
+            release();
+            throw err;
+        }
+    }
+    /**
+     * Prepared and execute a callback on a SQL statement. After the callback completes the statement is disposed.
+     * Use this method for SQL statements are either not expected to be reused, or are not expensive to prepare.
+     * For statements that will be reused often, instead use [[withPreparedSqliteStatement]].
+     * @param sql The SQLite SQL statement to execute
+     * @param callback the callback to invoke on the prepared statement
+     * @param logErrors Determines if error will be logged if statement fail to prepare
+     * @returns the value returned by `callback`.
+     * @public
+     */
+    withSqliteStatement(sql, callback, logErrors = true) {
+        const stmt = this.prepareSqliteStatement(sql, logErrors);
+        const release = () => stmt.dispose();
+        try {
+            const val = callback(stmt);
+            if (val instanceof Promise) {
+                val.then(release, release);
+            }
+            else {
+                release();
+            }
+            return val;
+        }
+        catch (err) {
+            release();
+            throw err;
+        }
+    }
+    /** Prepare an SQL statement.
+     * @param sql The SQLite SQL statement to prepare
+     * @param logErrors Determines if error will be logged if statement fail to prepare
+     * @throws [IModelError]($common) if there is a problem preparing the statement.
+     * @internal
+     */
+    prepareSqliteStatement(sql, logErrors = true) {
+        const stmt = new SqliteStatement_1.SqliteStatement(sql);
+        stmt.prepare(this.nativeDb, logErrors);
+        return stmt;
+    }
+    /** @internal */
+    get nativeDb() {
+        return this._nativeDb;
+    }
+    /** Allow to execute query and read results along with meta data. The result are streamed.
+     * @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 *ECSqlQueryReader* which help iterate over result set and also give access to meta data.
+     * @beta
+     * */
+    createQueryReader(ecsql, params, config) {
+        if (!this._nativeDb || !this._nativeDb.isOpen()) {
+            throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "db not open");
+        }
+        const executor = {
+            execute: async (request) => {
+                return ConcurrentQuery_1.ConcurrentQuery.executeQueryRequest(this._nativeDb, request);
+            },
+        };
+        return new core_common_1.ECSqlReader(executor, ecsql, params, config);
+    }
+    /** Execute a query and stream its results
+     * The result of the query is async iterator over the rows. The iterator will get next page automatically once rows in current page has been read.
+     * [ECSQL row]($docs/learning/ECSQLRowFormat).
+     *
+     * See also:
+     * - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
+     * - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
+     *
+     * @param ecsql The ECSQL statement to execute
+     * @param params The values to bind to the parameters (if the ECSQL has any).
+     * @param rowFormat Specify what format the row will be returned. It default to Array format though to make it compilable with previous version use *QueryRowFormat.UseJsPropertyNames*
+     * @param options Allow to specify certain flags which control how query is executed.
+     * @returns Returns the query result as an *AsyncIterableIterator<any>*  which lazy load result as needed. The row format is determined by *rowFormat* parameter.
+     * See [ECSQL row format]($docs/learning/ECSQLRowFormat) for details about the format of the returned rows.
+     * @throws [IModelError]($common) If there was any error while submitting, preparing or stepping into query
+     */
+    async *query(ecsql, params, rowFormat = core_common_1.QueryRowFormat.UseArrayIndexes, options) {
+        const builder = new core_common_1.QueryOptionsBuilder(options);
+        if (rowFormat === core_common_1.QueryRowFormat.UseJsPropertyNames) {
+            builder.setConvertClassIdsToNames(true);
+        }
+        const reader = this.createQueryReader(ecsql, params, builder.getOptions());
+        while (await reader.step())
+            yield reader.formatCurrentRow(rowFormat);
+    }
+    /** Compute number of rows that would be returned by the ECSQL.
+     *
+     * See also:
+     * - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
+     * - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
+     *
+     * @param ecsql The ECSQL statement to execute
+     * @param params The values to bind to the parameters (if the ECSQL has any).
+     * See "[iModel.js Types used in ECSQL Parameter Bindings]($docs/learning/ECSQLParameterTypes)" for details.
+     * @returns Return row count.
+     * @throws [IModelError]($common) If the statement is invalid
+     */
+    async queryRowCount(ecsql, params) {
+        for await (const row of this.query(`select count(*) from (${ecsql})`, params)) {
+            return row[0];
+        }
+        throw new core_common_1.IModelError(core_bentley_1.DbResult.BE_SQLITE_ERROR, "Failed to get row count");
+    }
+    /** Cancel any previous query with same token and run execute the current specified query.
+     * The result of the query is async iterator over the rows. The iterator will get next page automatically once rows in current page has been read.
+     * [ECSQL row]($docs/learning/ECSQLRowFormat).
+     *
+     * See also:
+     * - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
+     * - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
+     *
+     * @param ecsql The ECSQL statement to execute
+     * @param token None empty restart token. The previous query with same token would be cancelled. This would cause
+     * exception which user code must handle.
+     * @param params The values to bind to the parameters (if the ECSQL has any).
+     * @param rowFormat Specify what format the row will be returned. It default to Array format though to make it compilable with previous version use *QueryRowFormat.UseJsPropertyNames*
+     * @param options Allow to specify certain flags which control how query is executed.
+     * @returns Returns the query result as an *AsyncIterableIterator<any>*  which lazy load result as needed. The row format is determined by *rowFormat* parameter.
+     * See [ECSQL row format]($docs/learning/ECSQLRowFormat) for details about the format of the returned rows.
+     * @throws [IModelError]($common) If there was any error while submitting, preparing or stepping into query
+     */
+    async *restartQuery(token, ecsql, params, rowFormat = core_common_1.QueryRowFormat.UseArrayIndexes, options) {
+        for await (const row of this.query(ecsql, params, rowFormat, new core_common_1.QueryOptionsBuilder(options).setRestartToken(token).getOptions())) {
+            yield row;
+        }
+    }
+}
+exports.ECDb = ECDb;
+//# sourceMappingURL=ECDb.js.map

package/lib/cjs/ECDb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ECDb.js","sourceRoot":"","sources":["../../src/ECDb.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\nimport { IModelJsNative } from \"@bentley/imodeljs-native\";\r\n/** @packageDocumentation\r\n * @module ECDb\r\n */\r\nimport { DbResult, IDisposable, Logger, OpenMode } from \"@itwin/core-bentley\";\r\nimport { DbQueryRequest, ECSqlReader, IModelError, QueryBinder, QueryOptions, QueryOptionsBuilder, QueryRowFormat } from \"@itwin/core-common\";\r\nimport { BackendLoggerCategory } from \"./BackendLoggerCategory\";\r\nimport { ConcurrentQuery } from \"./ConcurrentQuery\";\r\nimport { ECSqlStatement } from \"./ECSqlStatement\";\r\nimport { IModelHost } from \"./IModelHost\";\r\nimport { SqliteStatement, StatementCache } from \"./SqliteStatement\";\r\n\r\nconst loggerCategory: string = BackendLoggerCategory.ECDb;\r\n\r\n/** Modes for how to open [ECDb]($backend) files.\r\n * @public\r\n */\r\nexport enum ECDbOpenMode {\r\n  Readonly,\r\n  ReadWrite,\r\n  /** Opens the file read-write and upgrades the file if necessary to the latest file format version. */\r\n  FileUpgrade,\r\n}\r\n\r\n/** An ECDb file\r\n * @public\r\n */\r\nexport class ECDb implements IDisposable {\r\n  private _nativeDb?: IModelJsNative.ECDb;\r\n  private _concurrentQueryInitialized: boolean = false;\r\n  private readonly _statementCache = new StatementCache<ECSqlStatement>();\r\n  private _sqliteStatementCache = new StatementCache<SqliteStatement>();\r\n  private _concurrentQueryStats = { resetTimerHandle: (null as any), logTimerHandle: (null as any), lastActivityTime: Date.now(), dispose: () => { } };\r\n\r\n  /** only for tests\r\n   * @internal\r\n   */\r\n  public resetSqliteCache(size: number) {\r\n    this._sqliteStatementCache.clear();\r\n    this._sqliteStatementCache = new StatementCache<SqliteStatement>(size);\r\n  }\r\n\r\n  constructor() {\r\n    this._nativeDb = new IModelHost.platform.ECDb();\r\n  }\r\n  /** Call this function when finished with this ECDb object. This releases the native resources held by the\r\n   *  ECDb object.\r\n   */\r\n  public dispose(): void {\r\n    if (!this._nativeDb)\r\n      return;\r\n\r\n    this.closeDb();\r\n    this._nativeDb.dispose();\r\n    this._nativeDb = undefined;\r\n  }\r\n\r\n  /** Create an ECDb\r\n   * @param pathName The path to the ECDb file to create.\r\n   * @throws [IModelError]($common) if the operation failed.\r\n   */\r\n  public createDb(pathName: string): void {\r\n    const status: DbResult = this.nativeDb.createDb(pathName);\r\n    if (status !== DbResult.BE_SQLITE_OK)\r\n      throw new IModelError(status, \"Failed to created ECDb\");\r\n  }\r\n\r\n  /** Open the ECDb.\r\n   * @param pathName The path to the ECDb file to open\r\n   * @param openMode Open mode\r\n   * @throws [IModelError]($common) if the operation failed.\r\n   */\r\n  public openDb(pathName: string, openMode: ECDbOpenMode = ECDbOpenMode.Readonly): void {\r\n    const nativeOpenMode: OpenMode = openMode === ECDbOpenMode.Readonly ? OpenMode.Readonly : OpenMode.ReadWrite;\r\n    const tryUpgrade: boolean = openMode === ECDbOpenMode.FileUpgrade;\r\n    const status: DbResult = this.nativeDb.openDb(pathName, nativeOpenMode, tryUpgrade);\r\n    if (status !== DbResult.BE_SQLITE_OK)\r\n      throw new IModelError(status, \"Failed to open ECDb\");\r\n  }\r\n\r\n  /** Returns true if the ECDb is open */\r\n  public get isOpen(): boolean { return this.nativeDb.isOpen(); }\r\n\r\n  /** Close the Db after saving any uncommitted changes.\r\n   * @throws [IModelError]($common) if the database is not open.\r\n   */\r\n  public closeDb(): void {\r\n    this._statementCache.clear();\r\n    this._sqliteStatementCache.clear();\r\n    this.nativeDb.closeDb();\r\n    this._concurrentQueryStats.dispose();\r\n  }\r\n\r\n  /** @internal use to test statement caching */\r\n  public clearStatementCache() {\r\n    this._statementCache.clear();\r\n  }\r\n\r\n  /** @internal use to test statement caching */\r\n  public getCachedStatementCount() {\r\n    return this._statementCache.size;\r\n  }\r\n\r\n  /** Commit the outermost transaction, writing changes to the file. Then, restart the transaction.\r\n   * @param changesetName The name of the operation that generated these changes.\r\n   * @throws [IModelError]($common) if the database is not open or if the operation failed.\r\n   */\r\n  public saveChanges(changesetName?: string): void {\r\n    const status: DbResult = this.nativeDb.saveChanges(changesetName);\r\n    if (status !== DbResult.BE_SQLITE_OK)\r\n      throw new IModelError(status, \"Failed to save changes\");\r\n  }\r\n\r\n  /** Abandon (cancel) the outermost transaction, discarding all changes since last save. Then, restart the transaction.\r\n   * @throws [IModelError]($common) if the database is not open or if the operation failed.\r\n   */\r\n  public abandonChanges(): void {\r\n    const status: DbResult = this.nativeDb.abandonChanges();\r\n    if (status !== DbResult.BE_SQLITE_OK)\r\n      throw new IModelError(status, \"Failed to abandon changes\");\r\n  }\r\n\r\n  /** Import a schema.\r\n   *\r\n   * If the import was successful, the database is automatically saved to disk.\r\n   * @param pathName Path to ECSchema XML file to import.\r\n   * @throws [IModelError]($common) if the database is not open or if the operation failed.\r\n   */\r\n  public importSchema(pathName: string): void {\r\n    const status: DbResult = this.nativeDb.importSchema(pathName);\r\n    if (status !== DbResult.BE_SQLITE_OK) {\r\n      Logger.logError(loggerCategory, `Failed to import schema from '${pathName}'.`);\r\n      throw new IModelError(status, `Failed to import schema from '${pathName}'.`);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Use a prepared ECSQL statement, potentially from the statement cache. If the requested statement doesn't exist\r\n   * in the statement cache, a new statement is prepared. After the callback completes, the statement is reset and saved\r\n   * in the statement cache so it can be reused in the future. Use this method for ECSQL statements that will be\r\n   * reused often and are expensive to prepare. The statement cache holds the most recently used statements, discarding\r\n   * the oldest statements as it fills. For statements you don't intend to reuse, instead use [[withStatement]].\r\n   * @param sql The SQLite SQL statement to execute\r\n   * @param callback the callback to invoke on the prepared statement\r\n   * @param logErrors Determines if error will be logged if statement fail to prepare\r\n   * @returns the value returned by `callback`.\r\n   * @see [[withStatement]]\r\n   * @public\r\n   */\r\n  public withPreparedStatement<T>(ecsql: string, callback: (stmt: ECSqlStatement) => T, logErrors = true): T {\r\n    const stmt = this._statementCache.findAndRemove(ecsql) ?? this.prepareStatement(ecsql, logErrors);\r\n    const release = () => this._statementCache.addOrDispose(stmt);\r\n    try {\r\n      const val = callback(stmt);\r\n      if (val instanceof Promise) {\r\n        val.then(release, release);\r\n      } else {\r\n        release();\r\n      }\r\n      return val;\r\n    } catch (err) {\r\n      release();\r\n      throw err;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Prepared and execute a callback on an ECSQL statement. After the callback completes the statement is disposed.\r\n   * Use this method for ECSQL statements are either not expected to be reused, or are not expensive to prepare.\r\n   * For statements that will be reused often, instead use [[withPreparedStatement]].\r\n   * @param sql The SQLite SQL statement to execute\r\n   * @param callback the callback to invoke on the prepared statement\r\n   * @param logErrors Determines if error will be logged if statement fail to prepare\r\n   * @returns the value returned by `callback`.\r\n   * @see [[withPreparedStatement]]\r\n   * @public\r\n   */\r\n  public withStatement<T>(ecsql: string, callback: (stmt: ECSqlStatement) => T, logErrors = true): T {\r\n    const stmt = this.prepareStatement(ecsql, logErrors);\r\n    const release = () => stmt.dispose();\r\n    try {\r\n      const val = callback(stmt);\r\n      if (val instanceof Promise) {\r\n        val.then(release, release);\r\n      } else {\r\n        release();\r\n      }\r\n      return val;\r\n    } catch (err) {\r\n      release();\r\n      throw err;\r\n    }\r\n  }\r\n\r\n  /** Prepare an ECSQL statement.\r\n   * @param ecsql The ECSQL statement to prepare\r\n   * @param logErrors Determines if error will be logged if statement fail to prepare\r\n   * @throws [IModelError]($common) if there is a problem preparing the statement.\r\n   */\r\n  public prepareStatement(ecsql: string, logErrors = true): ECSqlStatement {\r\n    const stmt = new ECSqlStatement();\r\n    stmt.prepare(this.nativeDb, ecsql, logErrors);\r\n    return stmt;\r\n  }\r\n\r\n  /**\r\n   * Use a prepared SQL statement, potentially from the statement cache. If the requested statement doesn't exist\r\n   * in the statement cache, a new statement is prepared. After the callback completes, the statement is reset and saved\r\n   * in the statement cache so it can be reused in the future. Use this method for SQL statements that will be\r\n   * reused often and are expensive to prepare. The statement cache holds the most recently used statements, discarding\r\n   * the oldest statements as it fills. For statements you don't intend to reuse, instead use [[withSqliteStatement]].\r\n   * @param sql The SQLite SQL statement to execute\r\n   * @param callback the callback to invoke on the prepared statement\r\n   * @param logErrors Determines if error will be logged if statement fail to prepare\r\n   * @returns the value returned by `callback`.\r\n   * @see [[withPreparedStatement]]\r\n   * @public\r\n   */\r\n  public withPreparedSqliteStatement<T>(sql: string, callback: (stmt: SqliteStatement) => T, logErrors = true): T {\r\n    const stmt = this._sqliteStatementCache.findAndRemove(sql) ?? this.prepareSqliteStatement(sql, logErrors);\r\n    const release = () => this._sqliteStatementCache.addOrDispose(stmt);\r\n    try {\r\n      const val: T = callback(stmt);\r\n      if (val instanceof Promise) {\r\n        val.then(release, release);\r\n      } else {\r\n        release();\r\n      }\r\n      return val;\r\n    } catch (err) {\r\n      release();\r\n      throw err;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Prepared and execute a callback on a SQL statement. After the callback completes the statement is disposed.\r\n   * Use this method for SQL statements are either not expected to be reused, or are not expensive to prepare.\r\n   * For statements that will be reused often, instead use [[withPreparedSqliteStatement]].\r\n   * @param sql The SQLite SQL statement to execute\r\n   * @param callback the callback to invoke on the prepared statement\r\n   * @param logErrors Determines if error will be logged if statement fail to prepare\r\n   * @returns the value returned by `callback`.\r\n   * @public\r\n   */\r\n  public withSqliteStatement<T>(sql: string, callback: (stmt: SqliteStatement) => T, logErrors = true): T {\r\n    const stmt = this.prepareSqliteStatement(sql, logErrors);\r\n    const release = () => stmt.dispose();\r\n    try {\r\n      const val: T = callback(stmt);\r\n      if (val instanceof Promise) {\r\n        val.then(release, release);\r\n      } else {\r\n        release();\r\n      }\r\n      return val;\r\n    } catch (err) {\r\n      release();\r\n      throw err;\r\n    }\r\n  }\r\n\r\n  /** Prepare an SQL statement.\r\n   * @param sql The SQLite SQL statement to prepare\r\n   * @param logErrors Determines if error will be logged if statement fail to prepare\r\n   * @throws [IModelError]($common) if there is a problem preparing the statement.\r\n   * @internal\r\n   */\r\n  public prepareSqliteStatement(sql: string, logErrors = true): SqliteStatement {\r\n    const stmt = new SqliteStatement(sql);\r\n    stmt.prepare(this.nativeDb, logErrors);\r\n    return stmt;\r\n  }\r\n\r\n  /** @internal */\r\n  public get nativeDb(): IModelJsNative.ECDb {\r\n    return this._nativeDb!;\r\n  }\r\n\r\n  /** Allow to execute query and read results along with meta data. The result are streamed.\r\n   * @param params The values to bind to the parameters (if the ECSQL has any).\r\n   * @param config Allow to specify certain flags which control how query is executed.\r\n   * @returns Returns *ECSqlQueryReader* which help iterate over result set and also give access to meta data.\r\n   * @beta\r\n   * */\r\n  public createQueryReader(ecsql: string, params?: QueryBinder, config?: QueryOptions): ECSqlReader {\r\n    if (!this._nativeDb || !this._nativeDb.isOpen()) {\r\n      throw new IModelError(DbResult.BE_SQLITE_ERROR, \"db not open\");\r\n    }\r\n    const executor = {\r\n      execute: async (request: DbQueryRequest) => {\r\n        return ConcurrentQuery.executeQueryRequest(this._nativeDb!, request);\r\n      },\r\n    };\r\n    return new ECSqlReader(executor, ecsql, params, config);\r\n  }\r\n\r\n  /** Execute a query and stream its results\r\n   * The result of the query is async iterator over the rows. The iterator will get next page automatically once rows in current page has been read.\r\n   * [ECSQL row]($docs/learning/ECSQLRowFormat).\r\n   *\r\n   * See also:\r\n   * - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)\r\n   * - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)\r\n   *\r\n   * @param ecsql The ECSQL statement to execute\r\n   * @param params The values to bind to the parameters (if the ECSQL has any).\r\n   * @param rowFormat Specify what format the row will be returned. It default to Array format though to make it compilable with previous version use *QueryRowFormat.UseJsPropertyNames*\r\n   * @param options Allow to specify certain flags which control how query is executed.\r\n   * @returns Returns the query result as an *AsyncIterableIterator<any>*  which lazy load result as needed. The row format is determined by *rowFormat* parameter.\r\n   * See [ECSQL row format]($docs/learning/ECSQLRowFormat) for details about the format of the returned rows.\r\n   * @throws [IModelError]($common) If there was any error while submitting, preparing or stepping into query\r\n   */\r\n  public async * query(ecsql: string, params?: QueryBinder, rowFormat = QueryRowFormat.UseArrayIndexes, options?: QueryOptions): AsyncIterableIterator<any> {\r\n    const builder = new QueryOptionsBuilder(options);\r\n    if (rowFormat === QueryRowFormat.UseJsPropertyNames) {\r\n      builder.setConvertClassIdsToNames(true);\r\n    }\r\n    const reader = this.createQueryReader(ecsql, params, builder.getOptions());\r\n    while (await reader.step())\r\n      yield reader.formatCurrentRow(rowFormat);\r\n  }\r\n  /** Compute number of rows that would be returned by the ECSQL.\r\n   *\r\n   * See also:\r\n   * - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)\r\n   * - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)\r\n   *\r\n   * @param ecsql The ECSQL statement to execute\r\n   * @param params The values to bind to the parameters (if the ECSQL has any).\r\n   * See \"[iModel.js Types used in ECSQL Parameter Bindings]($docs/learning/ECSQLParameterTypes)\" for details.\r\n   * @returns Return row count.\r\n   * @throws [IModelError]($common) If the statement is invalid\r\n   */\r\n  public async queryRowCount(ecsql: string, params?: QueryBinder): Promise<number> {\r\n    for await (const row of this.query(`select count(*) from (${ecsql})`, params)) {\r\n      return row[0] as number;\r\n    }\r\n    throw new IModelError(DbResult.BE_SQLITE_ERROR, \"Failed to get row count\");\r\n  }\r\n\r\n  /** Cancel any previous query with same token and run execute the current specified query.\r\n   * The result of the query is async iterator over the rows. The iterator will get next page automatically once rows in current page has been read.\r\n   * [ECSQL row]($docs/learning/ECSQLRowFormat).\r\n   *\r\n   * See also:\r\n   * - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)\r\n   * - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)\r\n   *\r\n   * @param ecsql The ECSQL statement to execute\r\n   * @param token None empty restart token. The previous query with same token would be cancelled. This would cause\r\n   * exception which user code must handle.\r\n   * @param params The values to bind to the parameters (if the ECSQL has any).\r\n   * @param rowFormat Specify what format the row will be returned. It default to Array format though to make it compilable with previous version use *QueryRowFormat.UseJsPropertyNames*\r\n   * @param options Allow to specify certain flags which control how query is executed.\r\n   * @returns Returns the query result as an *AsyncIterableIterator<any>*  which lazy load result as needed. The row format is determined by *rowFormat* parameter.\r\n   * See [ECSQL row format]($docs/learning/ECSQLRowFormat) for details about the format of the returned rows.\r\n   * @throws [IModelError]($common) If there was any error while submitting, preparing or stepping into query\r\n   */\r\n  public async * restartQuery(token: string, ecsql: string, params?: QueryBinder, rowFormat = QueryRowFormat.UseArrayIndexes, options?: QueryOptions): AsyncIterableIterator<any> {\r\n    for await (const row of this.query(ecsql, params, rowFormat, new QueryOptionsBuilder(options).setRestartToken(token).getOptions())) {\r\n      yield row;\r\n    }\r\n  }\r\n}\r\n"]}

package/lib/cjs/ECSchemaXmlContext.d.ts

@@ -0,0 +1,18 @@
+/** @packageDocumentation
+ * @module Schema
+ */
+import { IModelJsNative } from "@bentley/imodeljs-native";
+/** @internal */
+export declare type SchemaKey = IModelJsNative.ECSchemaXmlContext.SchemaKey;
+/** @internal */
+export declare type SchemaMatchType = IModelJsNative.ECSchemaXmlContext.SchemaMatchType;
+/** @internal */
+export declare class ECSchemaXmlContext {
+    private _nativeContext;
+    constructor();
+    addSchemaPath(searchPath: string): void;
+    setSchemaLocater(locater: IModelJsNative.ECSchemaXmlContext.SchemaLocaterCallback): void;
+    setFirstSchemaLocater(locater: IModelJsNative.ECSchemaXmlContext.SchemaLocaterCallback): void;
+    readSchemaFromXmlFile(filePath: string): any;
+}
+//# sourceMappingURL=ECSchemaXmlContext.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ECSchemaXmlContext.d.ts","sourceRoot":"","sources":["../../src/ECSchemaXmlContext.ts"],"names":[],"mappings":"AAIA;;GAEG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG1D,gBAAgB;AAChB,oBAAY,SAAS,GAAG,cAAc,CAAC,kBAAkB,CAAC,SAAS,CAAC;AAEpE,gBAAgB;AAChB,oBAAY,eAAe,GAAG,cAAc,CAAC,kBAAkB,CAAC,eAAe,CAAC;AAEhF,gBAAgB;AAChB,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,cAAc,CAAgD;;IAM/D,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAIvC,gBAAgB,CAAC,OAAO,EAAE,cAAc,CAAC,kBAAkB,CAAC,qBAAqB,GAAG,IAAI;IAIxF,qBAAqB,CAAC,OAAO,EAAE,cAAc,CAAC,kBAAkB,CAAC,qBAAqB,GAAG,IAAI;IAI7F,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG;CAQpD"}