@itwin/core-backend 4.0.0-dev.23 → 4.0.0-dev.24

package/lib/cjs/SQLiteDb.d.ts

@@ -1,220 +1,220 @@
-/** @packageDocumentation
- * @module SQLiteDb
- */
-import { IModelJsNative } from "@bentley/imodeljs-native";
-import { DbResult, IDisposable, OpenMode } from "@itwin/core-bentley";
-import { LocalFileName } from "@itwin/core-common";
-import { CloudSqlite } from "./CloudSqlite";
-import { SqliteStatement } from "./SqliteStatement";
-/** A SQLiteDb file
- * @public
- */
-export declare class SQLiteDb implements IDisposable {
-    /** @internal */
-    readonly nativeDb: IModelJsNative.SQLiteDb;
-    private _sqliteStatementCache;
-    /** @internal */
-    static createBlobIO(): SQLiteDb.BlobIO;
-    /** alias for closeDb. */
-    dispose(): void;
-    /** Create a SQLiteDb
-     * @param dbName The path to the SQLiteDb file to create.
-     */
-    createDb(dbName: string): void;
-    /** @beta */
-    createDb(dbName: string, container?: CloudSqlite.CloudContainer, params?: SQLiteDb.CreateParams): void;
-    /** Open a SQLiteDb.
-     * @param dbName The path to the SQLiteDb file to open
-     */
-    openDb(dbName: string, openMode: OpenMode | SQLiteDb.OpenParams): void;
-    /**
-     * @param container optional CloudContainer holding database
-     * @beta
-     */
-    openDb(dbName: string, openMode: OpenMode | SQLiteDb.OpenParams, container?: CloudSqlite.CloudContainer): void;
-    /** Close SQLiteDb.
-     * @param saveChanges if true, call `saveChanges` before closing db. Otherwise unsaved changes are abandoned.
-     */
-    closeDb(saveChanges?: boolean): void;
-    /** Returns true if this SQLiteDb is open */
-    get isOpen(): boolean;
-    /** Returns true if this SQLiteDb is open readonly */
-    get isReadonly(): boolean;
-    /**
-     * Open a database, perform an operation, then close the database.
-     *
-     * Details:
-     * - if database is open, throw an error
-     * - open a database
-     * - call a function with the database opened. If it is async, await its return.
-     * - if function throws, abandon all changes, close database, and rethrow
-     * - save all changes
-     * - close the database
-     * @return value from operation
-     */
-    withOpenDb<T>(args: SQLiteDb.WithOpenDbArgs, operation: () => T): T;
-    /**
-     * Perform an operation on a database in a CloudContainer with the write lock held.
-     *
-     * Details:
-     * - acquire the write lock on a CloudContainer
-     * - call `withOpenDb` with openMode `ReadWrite`
-     * - upload changes
-     * - release the write lock
-     * @param args arguments to lock the container and open the database
-     * @param operation an operation performed on the database with the write lock held.
-     * @return value from operation
-     * @internal
-     */
-    withLockedContainer<T>(args: CloudSqlite.LockAndOpenArgs, operation: () => T): Promise<T>;
-    /** vacuum this database
-     * @see https://www.sqlite.org/lang_vacuum.html
-     */
-    vacuum(args?: SQLiteDb.VacuumDbArgs): void;
-    /** Commit the outermost transaction, writing changes to the file. Then, restart the transaction. */
-    saveChanges(): void;
-    /** Abandon (cancel) the outermost transaction, discarding all changes since last save. Then, restart the transaction. */
-    abandonChanges(): void;
-    /**
-     * 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
-     * @returns the value returned by `callback`.
-     */
-    withPreparedSqliteStatement<T>(sql: string, callback: (stmt: SqliteStatement) => T): 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
-     * @returns the value returned by `callback`.
-     */
-    withSqliteStatement<T>(sql: string, callback: (stmt: SqliteStatement) => T): T;
-    /**
-     * Perform an operation on this database within a [savepoint](https://www.sqlite.org/lang_savepoint.html). If the operation completes successfully, the
-     * changes remain in the current transaction. If the operation throws an exception, the savepoint is rolled back
-     * and all changes to the database from this method are reversed, leaving the transaction exactly as it was before this method.
-     */
-    withSavePoint(savePointName: string, operation: () => void): void;
-    /** Prepare an SQL statement.
-       * @param sql The SQLite SQL statement to prepare
-       * @param logErrors Determine if errors are logged or not
-       * @internal
-       */
-    prepareSqliteStatement(sql: string, logErrors?: boolean): SqliteStatement;
-    /** execute an SQL statement */
-    executeSQL(sql: string): DbResult;
-}
-/** @public */
-export declare namespace SQLiteDb {
-    /** interface for reading and writing to a blob in a SQLiteDb
-     * @internal
-     */
-    interface BlobIO {
-        /** Close this BlobIO if it is opened.
-           * @note this BlobIO *may* be reused after this call by calling `open` again.
-          */
-        close(): void;
-        /** get the total number of bytes in the blob */
-        getNumBytes(): number;
-        /** @return true if this BlobIO was successfully opened and may be use to read or write the blob */
-        isValid(): boolean;
-        /** Open this BlobIO against a table/row/column in a Db */
-        open(
-        /** The database for the blob */
-        db: IModelJsNative.AnyDb, args: {
-            /** the name of the table for the blob*/
-            tableName: string;
-            /** the name of the column for the blob */
-            columnName: string;
-            /** The rowId of the blob */
-            row: number;
-            /** If true, open this BlobIO for write access */
-            writeable?: boolean;
-        }): void;
-        /** Read from a blob
-           * @returns the contents of the requested byte range
-           */
-        read(args: {
-            /** The number of bytes to read */
-            numBytes: number;
-            /** starting offset within the blob to read */
-            offset: number;
-            /** If present and of sufficient size, use this ArrayBuffer for the value. */
-            blob?: ArrayBuffer;
-        }): Uint8Array;
-        /** Reposition this BlobIO to a new rowId
-           * @note this BlobIO must be valid when this methods is called.
-           */
-        changeRow(row: number): void;
-        /** Write to a blob */
-        write(args: {
-            /** The number of bytes to write  */
-            numBytes: number;
-            /** starting offset within the blob to write */
-            offset: number;
-            /** the value to write */
-            blob: ArrayBuffer;
-        }): void;
-    }
-    /** Default transaction mode for SQLiteDbs.
-     * @see https://www.sqlite.org/lang_transaction.html
-     */
-    enum DefaultTxnMode {
-        /** no default transaction is started. You must use BEGIN/COMMIT or SQLite will use implicit transactions */
-        None = 0,
-        /** A deferred transaction is started when the file is first opened. This is the default. */
-        Deferred = 1,
-        /** An immediate transaction is started when the file is first opened. */
-        Immediate = 2,
-        /** An exclusive transaction is started when the file is first opened. */
-        Exclusive = 3
-    }
-    /** parameters common to opening or creating a new SQLiteDb */
-    interface OpenOrCreateParams {
-        /** If true, do not require that the `be_Prop` table exist */
-        rawSQLite?: boolean;
-        /** @see immutable option at https://www.sqlite.org/c3ref/open.html */
-        immutable?: boolean;
-        /** Do not attempt to verify that the file is a valid sQLite file before opening. */
-        skipFileCheck?: boolean;
-        /** the default transaction mode
-       * @see [[SQLiteDb.DefaultTxnMode]]
-      */
-        defaultTxn?: 0 | 1 | 2 | 3;
-        /** see query parameters from 'URI Filenames' in  https://www.sqlite.org/c3ref/open.html */
-        queryParam?: string;
-    }
-    /** Parameters for opening an existing SQLiteDb */
-    interface OpenParams extends OpenOrCreateParams {
-        /** use OpenMode.ReadWrite to open the file with write access */
-        openMode: OpenMode;
-    }
-    /** Size of a SQLiteDb page in bytes */
-    interface PageSize {
-        /** see https://www.sqlite.org/pragma.html#pragma_page_size */
-        pageSize?: number;
-    }
-    /** Parameters for creating a new SQLiteDb */
-    type CreateParams = OpenOrCreateParams & PageSize;
-    /** Arguments for `SqliteDb.withOpenDb` */
-    interface WithOpenDbArgs {
-        /** The name of the database to open */
-        dbName: string;
-        /** either an object with the open parameters or just OpenMode value. */
-        openMode?: OpenMode | SQLiteDb.OpenParams;
-        /** @internal */
-        container?: CloudSqlite.CloudContainer;
-    }
-    /** Arguments for `SQLiteDb.vacuum` */
-    interface VacuumDbArgs extends PageSize {
-        /** if present, name of new file to [vacuum into](https://www.sqlite.org/lang_vacuum.html) */
-        into?: LocalFileName;
-    }
-}
+/** @packageDocumentation
+ * @module SQLiteDb
+ */
+import { IModelJsNative } from "@bentley/imodeljs-native";
+import { DbResult, IDisposable, OpenMode } from "@itwin/core-bentley";
+import { LocalFileName } from "@itwin/core-common";
+import { CloudSqlite } from "./CloudSqlite";
+import { SqliteStatement } from "./SqliteStatement";
+/** A SQLiteDb file
+ * @public
+ */
+export declare class SQLiteDb implements IDisposable {
+    /** @internal */
+    readonly nativeDb: IModelJsNative.SQLiteDb;
+    private _sqliteStatementCache;
+    /** @internal */
+    static createBlobIO(): SQLiteDb.BlobIO;
+    /** alias for closeDb. */
+    dispose(): void;
+    /** Create a SQLiteDb
+     * @param dbName The path to the SQLiteDb file to create.
+     */
+    createDb(dbName: string): void;
+    /** @beta */
+    createDb(dbName: string, container?: CloudSqlite.CloudContainer, params?: SQLiteDb.CreateParams): void;
+    /** Open a SQLiteDb.
+     * @param dbName The path to the SQLiteDb file to open
+     */
+    openDb(dbName: string, openMode: OpenMode | SQLiteDb.OpenParams): void;
+    /**
+     * @param container optional CloudContainer holding database
+     * @beta
+     */
+    openDb(dbName: string, openMode: OpenMode | SQLiteDb.OpenParams, container?: CloudSqlite.CloudContainer): void;
+    /** Close SQLiteDb.
+     * @param saveChanges if true, call `saveChanges` before closing db. Otherwise unsaved changes are abandoned.
+     */
+    closeDb(saveChanges?: boolean): void;
+    /** Returns true if this SQLiteDb is open */
+    get isOpen(): boolean;
+    /** Returns true if this SQLiteDb is open readonly */
+    get isReadonly(): boolean;
+    /**
+     * Open a database, perform an operation, then close the database.
+     *
+     * Details:
+     * - if database is open, throw an error
+     * - open a database
+     * - call a function with the database opened. If it is async, await its return.
+     * - if function throws, abandon all changes, close database, and rethrow
+     * - save all changes
+     * - close the database
+     * @return value from operation
+     */
+    withOpenDb<T>(args: SQLiteDb.WithOpenDbArgs, operation: () => T): T;
+    /**
+     * Perform an operation on a database in a CloudContainer with the write lock held.
+     *
+     * Details:
+     * - acquire the write lock on a CloudContainer
+     * - call `withOpenDb` with openMode `ReadWrite`
+     * - upload changes
+     * - release the write lock
+     * @param args arguments to lock the container and open the database
+     * @param operation an operation performed on the database with the write lock held.
+     * @return value from operation
+     * @internal
+     */
+    withLockedContainer<T>(args: CloudSqlite.LockAndOpenArgs, operation: () => T): Promise<T>;
+    /** vacuum this database
+     * @see https://www.sqlite.org/lang_vacuum.html
+     */
+    vacuum(args?: SQLiteDb.VacuumDbArgs): void;
+    /** Commit the outermost transaction, writing changes to the file. Then, restart the transaction. */
+    saveChanges(): void;
+    /** Abandon (cancel) the outermost transaction, discarding all changes since last save. Then, restart the transaction. */
+    abandonChanges(): void;
+    /**
+     * 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
+     * @returns the value returned by `callback`.
+     */
+    withPreparedSqliteStatement<T>(sql: string, callback: (stmt: SqliteStatement) => T): 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
+     * @returns the value returned by `callback`.
+     */
+    withSqliteStatement<T>(sql: string, callback: (stmt: SqliteStatement) => T): T;
+    /**
+     * Perform an operation on this database within a [savepoint](https://www.sqlite.org/lang_savepoint.html). If the operation completes successfully, the
+     * changes remain in the current transaction. If the operation throws an exception, the savepoint is rolled back
+     * and all changes to the database from this method are reversed, leaving the transaction exactly as it was before this method.
+     */
+    withSavePoint(savePointName: string, operation: () => void): void;
+    /** Prepare an SQL statement.
+       * @param sql The SQLite SQL statement to prepare
+       * @param logErrors Determine if errors are logged or not
+       * @internal
+       */
+    prepareSqliteStatement(sql: string, logErrors?: boolean): SqliteStatement;
+    /** execute an SQL statement */
+    executeSQL(sql: string): DbResult;
+}
+/** @public */
+export declare namespace SQLiteDb {
+    /** interface for reading and writing to a blob in a SQLiteDb
+     * @internal
+     */
+    interface BlobIO {
+        /** Close this BlobIO if it is opened.
+           * @note this BlobIO *may* be reused after this call by calling `open` again.
+          */
+        close(): void;
+        /** get the total number of bytes in the blob */
+        getNumBytes(): number;
+        /** @return true if this BlobIO was successfully opened and may be use to read or write the blob */
+        isValid(): boolean;
+        /** Open this BlobIO against a table/row/column in a Db */
+        open(
+        /** The database for the blob */
+        db: IModelJsNative.AnyDb, args: {
+            /** the name of the table for the blob*/
+            tableName: string;
+            /** the name of the column for the blob */
+            columnName: string;
+            /** The rowId of the blob */
+            row: number;
+            /** If true, open this BlobIO for write access */
+            writeable?: boolean;
+        }): void;
+        /** Read from a blob
+           * @returns the contents of the requested byte range
+           */
+        read(args: {
+            /** The number of bytes to read */
+            numBytes: number;
+            /** starting offset within the blob to read */
+            offset: number;
+            /** If present and of sufficient size, use this ArrayBuffer for the value. */
+            blob?: ArrayBuffer;
+        }): Uint8Array;
+        /** Reposition this BlobIO to a new rowId
+           * @note this BlobIO must be valid when this methods is called.
+           */
+        changeRow(row: number): void;
+        /** Write to a blob */
+        write(args: {
+            /** The number of bytes to write  */
+            numBytes: number;
+            /** starting offset within the blob to write */
+            offset: number;
+            /** the value to write */
+            blob: ArrayBuffer;
+        }): void;
+    }
+    /** Default transaction mode for SQLiteDbs.
+     * @see https://www.sqlite.org/lang_transaction.html
+     */
+    enum DefaultTxnMode {
+        /** no default transaction is started. You must use BEGIN/COMMIT or SQLite will use implicit transactions */
+        None = 0,
+        /** A deferred transaction is started when the file is first opened. This is the default. */
+        Deferred = 1,
+        /** An immediate transaction is started when the file is first opened. */
+        Immediate = 2,
+        /** An exclusive transaction is started when the file is first opened. */
+        Exclusive = 3
+    }
+    /** parameters common to opening or creating a new SQLiteDb */
+    interface OpenOrCreateParams {
+        /** If true, do not require that the `be_Prop` table exist */
+        rawSQLite?: boolean;
+        /** @see immutable option at https://www.sqlite.org/c3ref/open.html */
+        immutable?: boolean;
+        /** Do not attempt to verify that the file is a valid sQLite file before opening. */
+        skipFileCheck?: boolean;
+        /** the default transaction mode
+       * @see [[SQLiteDb.DefaultTxnMode]]
+      */
+        defaultTxn?: 0 | 1 | 2 | 3;
+        /** see query parameters from 'URI Filenames' in  https://www.sqlite.org/c3ref/open.html */
+        queryParam?: string;
+    }
+    /** Parameters for opening an existing SQLiteDb */
+    interface OpenParams extends OpenOrCreateParams {
+        /** use OpenMode.ReadWrite to open the file with write access */
+        openMode: OpenMode;
+    }
+    /** Size of a SQLiteDb page in bytes */
+    interface PageSize {
+        /** see https://www.sqlite.org/pragma.html#pragma_page_size */
+        pageSize?: number;
+    }
+    /** Parameters for creating a new SQLiteDb */
+    type CreateParams = OpenOrCreateParams & PageSize;
+    /** Arguments for `SqliteDb.withOpenDb` */
+    interface WithOpenDbArgs {
+        /** The name of the database to open */
+        dbName: string;
+        /** either an object with the open parameters or just OpenMode value. */
+        openMode?: OpenMode | SQLiteDb.OpenParams;
+        /** @internal */
+        container?: CloudSqlite.CloudContainer;
+    }
+    /** Arguments for `SQLiteDb.vacuum` */
+    interface VacuumDbArgs extends PageSize {
+        /** if present, name of new file to [vacuum into](https://www.sqlite.org/lang_vacuum.html) */
+        into?: LocalFileName;
+    }
+}
 //# sourceMappingURL=SQLiteDb.d.ts.map