@itwin/core-backend 3.4.0 → 3.4.1

package/lib/cjs/ECDb.d.ts

@@ -1,192 +1,192 @@
-/** @packageDocumentation
- * @module ECDb
- */
-import { IDisposable } from "@itwin/core-bentley";
-import { IModelJsNative } from "@bentley/imodeljs-native";
-import { ECSqlReader, QueryBinder, QueryOptions } 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 readonly _statementCache;
-    private _sqliteStatementCache;
-    /** 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 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, 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 "[iTwin.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 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, options?: QueryOptions): AsyncIterableIterator<any>;
-}
+/** @packageDocumentation
+ * @module ECDb
+ */
+import { IDisposable } from "@itwin/core-bentley";
+import { IModelJsNative } from "@bentley/imodeljs-native";
+import { ECSqlReader, QueryBinder, QueryOptions } 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 readonly _statementCache;
+    private _sqliteStatementCache;
+    /** 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 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, 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 "[iTwin.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 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, options?: QueryOptions): AsyncIterableIterator<any>;
+}
 //# sourceMappingURL=ECDb.d.ts.map