@egi/smart-db 2.6.5 → 3.0.4

package/smart-db.d.ts

@@ -1,87 +1,483 @@
 import { BehaviorSubject, Observable } from "rxjs";
 import { AbstractModel } from "./models/abstract-model";
+import { ISmartLogDbWriter, SmartLog } from "@egi/smart-log";
 import { SmartDbVersionViewModel } from "./models/smart-db-version-view-model";
-import { GenericModelData, IndexedGenericModelData, SmartDbConnector, SmartDbDatabase, SmartDbOptions, SmartDbRunResult, SmartDbSqlOptions, SmartDbTableInfo, SqlFieldDescriptor, SqlLimit, SqlOrderBy, SqlUpdateValues, SqlValueType, SqlWhere } from "./smart-db-interfaces";
-import { SmartDbLog } from "./smart-db-log";
+import { AttributeInfo, GenericModelData, IndexedGenericModelData, MakeDbValueOptions, ModelClass, SmartDbConnector, SmartDbInterface, SmartDbOptions, SmartDbReadyState, SmartDbRunResult, SmartDbSqlOptions, SmartDbTableInfo, SqlFieldDescriptor, SqlLimit, SqlOrderBy, SqlUpdateValues, SqlValueType, SqlValueTypes, SqlWhere } from "./smart-db-interfaces";
 import { SmartDbSqlBuildData } from "./smart-db-sql-build-data";
 import { SmartError } from "./smart-error";
-export declare abstract class SmartDb {
+import { SmartDbDateTimeMode } from "./smart-tools";
+/**
+ * Abstract base class for all SmartDB database drivers.
+ *
+ * Provides a unified, type-safe API for SQL operations (SELECT, INSERT, UPDATE, DELETE),
+ * transaction management, schema upgrades, and logging across SQLite, MySQL, and Oracle.
+ *
+ * Concrete drivers extend this class and implement {@link getDatabaseType}, {@link getTableInfo},
+ * and {@link getDb}. Use the ready-state API ({@link databaseReady}, {@link onReady}) to wait
+ * for the database to finish initializing before issuing queries.
+ *
+ * @typeParam T - The concrete driver subclass (enables fluent `onReady` callbacks typed to the subclass).
+ */
+export declare abstract class SmartDb<T extends SmartDb<T>> implements SmartDbInterface {
+    /**
+     * Returns a short identifier for the underlying database engine,
+     * e.g. `"sqlite"`, `"mysql"`, or `"oracle"`.
+     * Used internally to locate the correct asset directory for SQL upgrade scripts.
+     */
     abstract getDatabaseType(): string;
+    /**
+     * Retrieves column metadata for a database table.
+     * @param table - The table name to inspect.
+     * @returns A {@link SmartDbTableInfo} describing the table's fields, name, and optional PK sequence.
+     */
     abstract getTableInfo(table: string): Promise<SmartDbTableInfo>;
-    protected: any;
-    readonly dbLogging: boolean;
+    /**
+     * Returns the raw underlying database connection/handle.
+     * The exact type depends on the driver (e.g. `better-sqlite3` `Database`, `mysql2` `Pool`).
+     * Prefer the higher-level SmartDB API over using this directly.
+     */
+    abstract getDb(): any;
+    protected _onReady: BehaviorSubject<SmartDbReadyState>;
+    protected db: any;
     protected dbConnector: SmartDbConnector;
     protected lastBuildData: SmartDbSqlBuildData;
-    protected smartDbLog: SmartDbLog;
-    protected _onReady: BehaviorSubject<boolean>;
-    protected db: SmartDbDatabase;
+    protected log: SmartLog;
+    private dbWriter;
+    protected options: SmartDbOptions<T>;
     private _lastError;
-    private dictionaries;
-    private _isReady;
-    protected constructor(dbConnector: SmartDbConnector, noDbLogging?: boolean);
-    buildSelectStatement<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), options: SmartDbSqlOptions<T, D>): SmartDbSqlBuildData;
-    close(): Promise<boolean>;
+    private readonly dictionaries;
+    private moduleVersions;
+    private waitReadySubscriptions;
+    protected constructor(dbConnector: SmartDbConnector, options?: SmartDbOptions<T>);
+    /** Returns the {@link SmartDbOptions} object that was passed to the constructor. */
+    getOptions(): SmartDbOptions<T>;
+    /** Whether database-level logging (persisting log entries to a DB table) is currently active. */
+    get dbLogging(): boolean;
+    /**
+     * `true` when the database has reached at least the {@link SmartDbReadyState.CONNECTED} state,
+     * meaning the underlying connection is established (though schema upgrades may still be running).
+     */
+    get isConnected(): boolean;
+    /**
+     * `true` when the database has reached {@link SmartDbReadyState.READY},
+     * meaning all connections and schema upgrades have completed successfully.
+     * Use {@link databaseReady} to await this state asynchronously.
+     */
+    get isReady(): boolean;
+    /** The last error that occurred, wrapped in a {@link SmartError}. */
+    get lastError(): SmartError;
+    set lastError(value: any);
+    /**
+     * RxJS observable that emits every time the ready state changes.
+     * Useful for reacting to connect/disconnect/error transitions.
+     * For a one-time await, prefer {@link databaseReady}.
+     */
+    get onReady(): Observable<SmartDbReadyState>;
+    /**
+     * The current {@link SmartDbReadyState} of the database connection.
+     * Progresses: `INIT` → `PREPARING` → `CONNECTED` → `READY` (or `ERROR` / `CLOSED`).
+     */
+    get readyState(): SmartDbReadyState;
+    protected set readyState(state: SmartDbReadyState);
+    /**
+     * `true` if this driver supports synchronous query methods
+     * (e.g. {@link getSync}, {@link insertSync}, {@link deleteSync}, {@link updateSync}).
+     * Only the SQLite driver returns `true`; MySQL and Oracle are async-only.
+     */
+    get supportSyncCalls(): boolean;
+    /**
+     * Returns a promise that resolves once the database reaches `targetState` (default: `READY`).
+     * Rejects with the last {@link SmartError} if the state transitions to `ERROR` first.
+     *
+     * @param targetState - The state to wait for. Defaults to {@link SmartDbReadyState.READY}.
+     * @returns A promise that resolves to the reached {@link SmartDbReadyState}.
+     *
+     * @example
+     * ```ts
+     * await db.databaseReady();
+     * const rows = await db.getAll(MyModel);
+     * ```
+     */
+    databaseReady(targetState?: SmartDbReadyState): Promise<SmartDbReadyState>;
+    /**
+     * Returns the version information for all database modules that were initialized
+     * during {@link initDb}. Useful for diagnostics and schema migration auditing.
+     */
+    getModuleVersions(): SmartDbVersionViewModel[];
+    /**
+     * Builds a SELECT SQL statement from the given model and options without executing it.
+     * The resulting {@link SmartDbSqlBuildData} contains the SQL string and bound parameter values.
+     * Also available via {@link getLastBuildData} after any query.
+     *
+     * @param modelClass - A model class (extends {@link AbstractModel}) or a raw table-name string.
+     * @param options - Query options: fields, WHERE, ORDER BY, GROUP BY, LIMIT, UNION/INTERSECT/MINUS, etc.
+     */
+    buildSelectStatement<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, options: SmartDbSqlOptions<T, D>): SmartDbSqlBuildData;
+    /** Closes the database connection synchronously. Only supported by drivers that implement synchronous calls. */
     closeSync(): boolean;
+    /**
+     * Commits the current transaction asynchronously.
+     * Delegates to {@link commitSync} — override in the driver if async commit is needed.
+     */
     commit(): Promise<void>;
+    /** Commits the current transaction synchronously. Throws if not implemented by the driver. */
     commitSync(): void;
-    delete<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), where?: SqlWhere): Promise<number>;
-    deleteSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), where?: SqlWhere): number | false;
-    exec(script: string): Promise<void>;
+    /**
+     * Deletes rows from the table associated with `modelClass` that match `where`.
+     * Omitting `where` deletes all rows.
+     *
+     * @param modelClass - A model class or raw table-name string.
+     * @param where - Optional WHERE clause. See {@link SqlWhere} for filter syntax.
+     * @returns The number of rows deleted.
+     * @throws {@link SmartError} if the statement fails.
+     */
+    delete<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, where?: SqlWhere): Promise<number>;
+    /**
+     * Synchronous variant of {@link delete}. Only available when {@link supportSyncCalls} is `true` (SQLite driver).
+     *
+     * @param modelClass - A model class or raw table-name string.
+     * @param where - Optional WHERE clause.
+     * @returns The number of rows deleted, or `false` if an error occurred.
+     * @throws A string error if the driver does not support sync calls.
+     */
+    deleteSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, where?: SqlWhere): number | false;
+    /**
+     * Executes a raw SQL statement asynchronously (no result rows returned).
+     * Delegates to {@link execSync} — override in the driver for native async execution.
+     *
+     * @param script - The SQL statement to execute.
+     * @param params - Optional positional parameters bound to `?` placeholders.
+     */
+    exec(script: string, params?: SqlValueType[]): Promise<void>;
+    /**
+     * Executes a multi-statement SQL script asynchronously, splitting on statement boundaries.
+     * Wraps execution in a transaction: rolls back and throws on error (unless the failing
+     * statement is a `DROP` and `ignoreDropError` is `true`).
+     *
+     * @param script - One or more SQL statements separated by statement terminators.
+     * @param ignoreDropError - When `true`, errors from `DROP` statements are silently skipped.
+     * @throws {@link SmartError} on the first non-DROP failure, after rolling back.
+     */
     execScript(script: string, ignoreDropError?: boolean): Promise<void>;
+    /**
+     * Synchronous variant of {@link execScript}. Only available when {@link supportSyncCalls} is `true`.
+     * Errors from `DROP` statements are silently ignored; all other errors are re-thrown.
+     *
+     * @param script - One or more SQL statements separated by statement terminators.
+     * @throws A string error if the driver does not support sync calls.
+     */
     execScriptSync(script: string): void;
-    execSync(script: string): boolean;
-    exists<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), type?: "view" | "table" | "index", indexTableName?: string): Promise<boolean>;
-    existsSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), type?: "view" | "table" | "index", indexTableName?: string): boolean;
-    get<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), options: SmartDbSqlOptions<T, D>): Promise<(T | D)[] | T | D | SqlValueType | IndexedGenericModelData<T, D> | string | string[] | false>;
-    getAll<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), where?: SqlWhere, fields?: string | string[] | null, orderBy?: SqlOrderBy, limit?: SqlLimit): Promise<T[] | false>;
-    getAllSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), where?: SqlWhere, fields?: string | string[] | null, orderBy?: SqlOrderBy, limit?: SqlLimit): T[] | false;
-    getDb(): SmartDbDatabase;
+    /**
+     * Executes a raw SQL statement synchronously. Throws if not implemented by the driver.
+     *
+     * @param script - The SQL statement to execute.
+     * @param params - Optional positional parameters bound to `?` placeholders.
+     * @returns `true` on success.
+     */
+    execSync(script: string, params?: SqlValueType[]): boolean;
+    /**
+     * Executes a raw SQL query asynchronously and returns all result rows.
+     * Delegates to {@link querySync} — override in the driver for native async execution.
+     *
+     * @param script - A SQL SELECT (or other query) statement.
+     * @param params - Optional positional parameters bound to `?` placeholders.
+     * @returns An array of plain objects keyed by column name.
+     */
+    query(script: string, params?: SqlValueType[]): Promise<GenericModelData[]>;
+    /**
+     * Executes a raw SQL query synchronously and returns all result rows.
+     * Throws if not implemented by the driver.
+     *
+     * @param script - A SQL SELECT (or other query) statement.
+     * @param params - Optional positional parameters bound to `?` placeholders.
+     * @returns An array of plain objects keyed by column name.
+     */
+    querySync(script: string, params?: SqlValueType[]): GenericModelData[];
+    /**
+     * Checks whether a table, view, or index exists in the database asynchronously.
+     * Delegates to {@link existsSync}.
+     *
+     * @param modelClass - A model class or raw table/view name string.
+     * @param type - Optional object type to check: `"table"`, `"view"`, or `"index"`.
+     * @param indexTableName - For `"index"` checks, the parent table name.
+     * @returns `true` if the object exists.
+     */
+    exists<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, type?: "view" | "table" | "index", indexTableName?: string): Promise<boolean>;
+    /**
+     * Synchronous variant of {@link exists}. Throws if not implemented by the driver.
+     *
+     * @param modelClass - A model class or raw table/view name string.
+     * @param type - Optional object type to check: `"table"`, `"view"`, or `"index"`.
+     * @param indexTableName - For `"index"` checks, the parent table name.
+     * @returns `true` if the object exists.
+     */
+    existsSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, type?: "view" | "table" | "index", indexTableName?: string): boolean;
+    /**
+     * The primary async query method. Executes a SELECT statement built from `options` and returns
+     * the results in one of several shapes depending on the options provided:
+     *
+     * - Default: an array of model instances (`T[]`).
+     * - `options.firstOnly = true`: a single model instance (`T`), or `false` if not found.
+     * - `options.count = true`: a numeric count value.
+     * - `options.style = FieldNamingStyle.Database`: plain objects with raw column names.
+     *
+     * For simpler call sites consider the convenience methods {@link getAll}, {@link getFirst},
+     * {@link getAllWithOptions}, and {@link getFirstWithOptionsSync}.
+     *
+     * @param modelClass - A model class or raw table-name string.
+     * @param options - Full query options ({@link SmartDbSqlOptions}).
+     */
+    get<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, options: SmartDbSqlOptions<T, D>): Promise<(T | D)[] | T | D | SqlValueType | IndexedGenericModelData<T, D> | string | string[] | false>;
+    /**
+     * Async convenience wrapper for {@link get} with `firstOnly: true`.
+     * Returns the first matching row as a typed model instance.
+     *
+     * @param modelClass - A model class or raw table-name string.
+     * @param options - Query options; `firstOnly` is forced to `true`.
+     * @returns The first matching model instance.
+     */
+    async<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, options: SmartDbSqlOptions<T, D>): Promise<T>;
+    /**
+     * Synchronous convenience wrapper for {@link getSync} with `firstOnly: true`.
+     * Only available when {@link supportSyncCalls} is `true` (SQLite driver).
+     *
+     * @param modelClass - A model class or raw table-name string.
+     * @param options - Query options; `firstOnly` is forced to `true`.
+     * @returns The first matching model instance, or `false` if none found.
+     */
+    getFirstWithOptionsSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, options: SmartDbSqlOptions<T, D>): T | false;
+    /**
+     * Async convenience wrapper for {@link get} that always returns a typed array.
+     *
+     * @param modelClass - A model class or raw table-name string.
+     * @param options - Full query options ({@link SmartDbSqlOptions}).
+     * @returns An array of model instances.
+     */
+    getAllWithOptions<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, options: SmartDbSqlOptions<T, D>): Promise<T[]>;
+    /**
+     * Synchronous convenience wrapper for {@link getSync} that always returns a typed array.
+     * Only available when {@link supportSyncCalls} is `true` (SQLite driver).
+     *
+     * @param modelClass - A model class or raw table-name string.
+     * @param options - Full query options ({@link SmartDbSqlOptions}).
+     * @returns An array of model instances, or `false` if an error occurred.
+     */
+    getAllWithOptionsSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, options: SmartDbSqlOptions<T, D>): T[] | false;
+    /**
+     * Retrieves all rows matching the given criteria as an array of typed model instances.
+     * A simpler alternative to {@link getAllWithOptions} for common query patterns.
+     *
+     * @param modelClass - A model class or raw table-name string.
+     * @param where - Optional WHERE clause ({@link SqlWhere}).
+     * @param fields - Optional field list to SELECT. Pass `null` or omit for all columns.
+     * @param orderBy - Optional ORDER BY clause (field name(s), optionally with `ASC`/`DESC`).
+     * @param limit - Optional LIMIT/OFFSET ({@link SqlLimit}).
+     * @returns An array of model instances.
+     */
+    getAll<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, where?: SqlWhere, fields?: string | string[] | null, orderBy?: SqlOrderBy, limit?: SqlLimit): Promise<T[]>;
+    /**
+     * Synchronous variant of {@link getAll}.
+     * Only available when {@link supportSyncCalls} is `true` (SQLite driver).
+     *
+     * @param modelClass - A model class or raw table-name string.
+     * @param where - Optional WHERE clause.
+     * @param fields - Optional field list. Pass `null` or omit for all columns.
+     * @param orderBy - Optional ORDER BY clause.
+     * @param limit - Optional LIMIT/OFFSET.
+     * @returns An array of model instances, or `false` if an error occurred.
+     */
+    getAllSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, where?: SqlWhere, fields?: string | string[] | null, orderBy?: SqlOrderBy, limit?: SqlLimit): T[] | false;
+    /** Returns the database connector (connection string or driver-specific connection object). */
     getDbConnector(): string | SmartDbConnector;
+    /**
+     * Returns the quoting character used to delimit identifiers (column/table names) in SQL.
+     * Defaults to `"` (ANSI SQL); drivers may override this (e.g. MySQL uses `` ` ``).
+     */
     getDbQuote(): string;
-    getFirst<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), where?: SqlWhere, fields?: string | string[] | null, orderBy?: SqlOrderBy): Promise<T | false>;
-    getFirstSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), where?: SqlWhere, fields?: string | string[] | null, orderBy?: SqlOrderBy): T | false;
-    getLastBuildData(): SmartDbSqlBuildData;
+    /**
+     * Retrieves the first row matching the given criteria as a typed model instance.
+     *
+     * @param modelClass - A model class or raw table-name string.
+     * @param where - Optional WHERE clause ({@link SqlWhere}).
+     * @param fields - Optional field list to SELECT.
+     * @param orderBy - Optional ORDER BY clause.
+     * @returns The first matching model instance.
+     */
+    getFirst<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, where?: SqlWhere, fields?: SqlFieldDescriptor | string | (SqlFieldDescriptor | string)[] | null, orderBy?: SqlOrderBy): Promise<T>;
+    /**
+     * Synchronous variant of {@link getFirst}.
+     * Only available when {@link supportSyncCalls} is `true` (SQLite driver).
+     *
+     * @param modelClass - A model class or raw table-name string.
+     * @param where - Optional WHERE clause.
+     * @param fields - Optional field list to SELECT.
+     * @param orderBy - Optional ORDER BY clause.
+     * @returns The first matching model instance, or `false` if none found or an error occurred.
+     */
+    getFirstSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, where?: SqlWhere, fields?: SqlFieldDescriptor | string | (SqlFieldDescriptor | string)[] | null, orderBy?: SqlOrderBy): T | false;
+    /**
+     * Returns the {@link SmartDbSqlBuildData} produced by the most recent query.
+     * Useful for debugging: inspect `buildData.sql` and `buildData.values` to see the
+     * exact SQL and parameters that were sent to the database.
+     */
+    getLastBuildData<T extends AbstractModel<T, D>, D extends GenericModelData>(): SmartDbSqlBuildData;
+    /** Returns the last {@link SmartError} that occurred. Equivalent to reading the {@link lastError} getter. */
     getLastError(): SmartError;
-    getLogger(): SmartDbLog;
-    getSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), options: SmartDbSqlOptions<T, D>): (T | D)[] | T | D | SqlValueType | IndexedGenericModelData<T, D> | string | string[] | false;
+    /** Returns the {@link SmartLog} logger instance used by this database connection. */
+    getLogger(): SmartLog;
+    /** Returns the current {@link ISmartLogDbWriter} used for database logging, or `null` if not active. */
+    getDbWriter(): ISmartLogDbWriter | null;
+    /**
+     * Checks whether the `smart_db_log` table exists and, if {@link SmartDbOptions.dbLogging} is enabled,
+     * installs a db writer on the logger. Called automatically during {@link initDb}.
+     */
+    enableDbLogging(): Promise<void>;
+    /**
+     * The primary synchronous query method. Only available when {@link supportSyncCalls} is `true` (SQLite driver).
+     * Mirrors {@link get} but executes synchronously. See {@link get} for full option/return-type documentation.
+     *
+     * @param modelClass - A model class or raw table-name string.
+     * @param options - Full query options ({@link SmartDbSqlOptions}).
+     * @throws A string error if the driver does not support sync calls.
+     */
+    getSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, options: SmartDbSqlOptions<T, D>): (T | D)[] | T | D | SqlValueType | IndexedGenericModelData<T, D> | string | string[] | false;
+    /**
+     * Returns `true` if the driver supports concurrent (nested/savepoint) transactions.
+     * The base implementation always returns `false`; override in drivers that support it.
+     */
     hasConcurrentTransactions(): boolean;
+    /**
+     * Returns `true` if a transaction is currently active on this connection.
+     * Throws if not implemented by the driver.
+     */
     hasTransaction(): boolean;
-    initDb(appOptions: SmartDbOptions): Promise<SmartDbVersionViewModel[]>;
-    insert<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), values: SqlUpdateValues | T): Promise<number>;
-    insertSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), values: SqlUpdateValues | T): number | false;
+    /**
+     * Initializes the database: runs the upgrade manager to apply any pending SQL migration
+     * scripts for the `smart-db-core` module and any user-defined modules specified in
+     * {@link SmartDbOptions.module}. Called automatically from the constructor unless
+     * `delayInit: true` is set.
+     *
+     * @returns An array of {@link SmartDbVersionViewModel} entries — one per initialized module.
+     */
+    initDb(): Promise<SmartDbVersionViewModel[]>;
+    /**
+     * Inserts a new row into the table associated with `modelClass`.
+     *
+     * @param modelClass - A model class or raw table-name string.
+     * @param values - A plain object of `{columnName: value}` pairs, or a model instance.
+     *   When passing a model instance its DB-style plain object is extracted automatically.
+     * @returns The auto-generated primary key (last insert ID) of the new row.
+     * @throws {@link SmartError} if the statement fails.
+     */
+    insert<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, values: SqlUpdateValues | T): Promise<number>;
+    /**
+     * Synchronous variant of {@link insert}.
+     * Only available when {@link supportSyncCalls} is `true` (SQLite driver).
+     *
+     * @param modelClass - A model class or raw table-name string.
+     * @param values - A plain object or model instance with the values to insert.
+     * @returns The last insert ID, or `false` if an error occurred.
+     * @throws A string error if the driver does not support sync calls.
+     */
+    insertSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, values: SqlUpdateValues | T): number | false;
+    /**
+     * Rolls back the current transaction asynchronously.
+     * Delegates to {@link rollbackSync} — override in the driver if async rollback is needed.
+     */
     rollback(): Promise<void>;
+    /** Rolls back the current transaction synchronously. Throws if not implemented by the driver. */
     rollbackSync(): void;
+    /**
+     * Converts a string, number (Unix ms), or `Date` to a JavaScript `Date`.
+     * Returns `null` for invalid or unparseable input.
+     *
+     * @param d - The value to convert.
+     */
     toDate(d: Date | number | string): Date | null;
+    /**
+     * Converts a JavaScript `Date` or Unix timestamp to a local-time database datetime string
+     * (`YYYY-MM-DD HH:MM:SS`). Use {@link AbstractModel.toDbDate} directly when zone control
+     * or millisecond precision is needed.
+     *
+     * @param d - The date to convert.
+     */
     toDbDate(d: Date | number): string;
+    /**
+     * Converts a JavaScript `Date` or Unix timestamp to a UTC-based ISO-like timestamp string
+     * (`YYYY-MM-DD HH:MM:SS.mmm`). Suitable for storing in `string`-typed columns when full
+     * precision is needed. For timezone-aware storage prefer {@link AbstractModel.toDbDate}.
+     *
+     * @param d - The date/time to convert.
+     */
     toDbTimestamp(d: Date | number): string;
-    update<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), values: SqlUpdateValues | T, where?: SqlWhere): Promise<number>;
-    updateSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), values: SqlUpdateValues | T, where?: SqlWhere): number | false;
-    protected statementRun(buildData: SmartDbSqlBuildData): Promise<SmartDbRunResult>;
-    protected statementRunSync(buildData: SmartDbSqlBuildData): SmartDbRunResult;
+    /**
+     * Updates rows in the table associated with `modelClass`.
+     *
+     * @param modelClass - A model class or raw table-name string.
+     * @param values - A plain object or model instance with the column values to set.
+     * @param where - Optional WHERE clause to restrict which rows are updated.
+     *   Omitting `where` updates all rows in the table.
+     * @returns The number of rows affected.
+     * @throws {@link SmartError} if the statement fails.
+     */
+    update<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, values: SqlUpdateValues | T, where?: SqlWhere): Promise<number>;
+    /**
+     * Synchronous variant of {@link update}.
+     * Only available when {@link supportSyncCalls} is `true` (SQLite driver).
+     *
+     * @param modelClass - A model class or raw table-name string.
+     * @param values - A plain object or model instance with the column values to set.
+     * @param where - Optional WHERE clause.
+     * @returns The number of rows affected, or `false` if an error occurred.
+     * @throws A string error if the driver does not support sync calls.
+     */
+    updateSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, values: SqlUpdateValues | T, where?: SqlWhere): number | false;
+    /**
+     * The active date/time conversion mode for this connection.
+     * Defaults to `"rule"` when not set in {@link SmartDbOptions}.
+     * See {@link SmartDbDateTimeMode} for the effect of each mode.
+     */
+    get dateTimeMode(): SmartDbDateTimeMode;
+    /**
+     * Converts a value to its database representation using the column's type metadata.
+     * Delegates to {@link AbstractModel.makeDbValue}; drivers may override to inject
+     * the connection's {@link dateTimeMode}.
+     *
+     * @param value - The JavaScript value to convert.
+     * @param options - Optional type hints: `dbFullType` and/or `dateTimeMode`.
+     */
+    makeDbValue(value: SqlValueType, options?: MakeDbValueOptions): SqlValueType;
+    protected buildDeleteStatement<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, where?: SqlWhere): SmartDbSqlBuildData;
+    protected buildFieldList<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, fields: (SqlValueType | SqlFieldDescriptor)[]): string[];
+    protected buildInsertStatement<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, values: SqlUpdateValues | T): SmartDbSqlBuildData;
+    protected buildSelectSectionStatement<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, options: SmartDbSqlOptions<T, D>): SmartDbSqlBuildData;
+    protected buildUpdateStatement<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, values: D | T, where?: SqlWhere): SmartDbSqlBuildData;
+    protected buildWhere<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, where: SqlWhere, op?: string): SmartDbSqlBuildData;
+    protected makeArgumentDbValue(value: SqlValueType, rawType?: string): SqlValueType;
+    protected getJsType(rawType?: string): SqlValueTypes;
+    protected prepareField<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, field: SqlValueType | SqlFieldDescriptor, values?: SqlValueType[]): string;
+    protected prepareFieldValue<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, fieldOperation: SqlFieldDescriptor): string;
+    protected saveExecute<T>(fn: () => T): T | false;
     protected statementGet<T extends object>(buildData: SmartDbSqlBuildData): Promise<T>;
-    protected statementGetSync(buildData: SmartDbSqlBuildData): any;
     protected statementGetAll<T>(buildData: SmartDbSqlBuildData): Promise<T[]>;
     protected statementGetAllSync(buildData: SmartDbSqlBuildData): any[];
-    protected buildWhere<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), where: SqlWhere, op?: string): SmartDbSqlBuildData;
-    protected buildDeleteStatement<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), where?: SqlWhere): SmartDbSqlBuildData;
-    protected buildUpdateStatement<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), values: D | T, where?: SqlWhere): SmartDbSqlBuildData;
-    protected buildInsertStatement<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), values: SqlUpdateValues | T): SmartDbSqlBuildData;
-    protected prepareFieldValue<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), fieldOperation: SqlFieldDescriptor): string;
-    protected prepareField<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), field: SqlValueType | SqlFieldDescriptor, values?: SqlValueType[]): string;
-    protected buildFieldList<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), fields: (SqlValueType | SqlFieldDescriptor)[]): string[];
-    protected buildSelectSectionStatement<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), options: SmartDbSqlOptions<T, D>): SmartDbSqlBuildData;
-    protected translateFieldName<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), field: string): string;
-    protected makeDbValue(value: SqlValueType): SqlValueType;
-    protected makeArgumentDbValue(value: SqlValueType): SqlValueType;
-    protected saveExecute<T>(fn: () => T): T | false;
+    protected statementGetSync(buildData: SmartDbSqlBuildData): any;
+    protected statementRun(buildData: SmartDbSqlBuildData): Promise<SmartDbRunResult>;
+    protected statementRunSync(buildData: SmartDbSqlBuildData): SmartDbRunResult;
+    protected getFieldInfo<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, field: string): AttributeInfo;
+    protected translateFieldName<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, field: string): string;
+    protected getFieldType<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, field: string): string;
+    protected getFieldFullType<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, field: string): string;
+    protected getTableClass<T extends AbstractModel<T, D>, D extends GenericModelData>(model: string | ModelClass<T>): ModelClass<T>;
+    protected getPkSequenceName<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>): string;
+    protected getTableName<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>): string;
     private scriptParser;
     private prepareResultRow;
     private prepareResultRows;
-    private getTableName;
-    get isReady(): boolean;
-    set isReady(ready: boolean);
-    get lastError(): SmartError;
-    set lastError(value: any);
-    get onReady(): Observable<boolean>;
-    get supportSyncCalls(): boolean;
+    /**
+     * Closes the database connection and cancels any pending ready-state subscriptions.
+     * Sets {@link readyState} to {@link SmartDbReadyState.CLOSED} then delegates to {@link closeSync}.
+     * @returns `true` if the connection was closed successfully.
+     */
+    close(): Promise<boolean>;
 }