@egi/smart-db 2.6.5 → 3.0.4

package/README.md

@@ -0,0 +1,355 @@
+# smart-db
+
+A unified, type-safe ORM abstraction layer for SQLite (better-sqlite3), MySQL, and Oracle. Provides a single API across all three databases with both synchronous and asynchronous access, a composable SQL builder, schema versioning, and optional database-backed logging.
+
+## Installation
+
+```bash
+npm install @egi/smart-db
+```
+
+Install only the driver(s) you need:
+
+```bash
+npm install better-sqlite3   # SQLite
+npm install mysql2            # MySQL
+npm install oracledb          # Oracle
+```
+
+## Quick Start
+
+### SQLite
+
+```typescript
+import { SmartDbBetterSqlite3 } from "@egi/smart-db/drivers/smart-db-better-sqlite3";
+
+const db = new SmartDbBetterSqlite3(
+  { filename: "./my-database.db" },
+  { module: "my-app", onReady: (db, err) => { /* ... */ } }
+);
+```
+
+### MySQL
+
+```typescript
+import { SmartDbMysql } from "@egi/smart-db/drivers/smart-db-mysql";
+
+const db = new SmartDbMysql(
+  { host: "localhost", user: "root", password: "secret", database: "mydb" },
+  { module: "my-app", onReady: (db, err) => { /* ... */ } }
+);
+```
+
+### Oracle
+
+```typescript
+import { SmartDbOracle } from "@egi/smart-db/drivers/smart-db-oracle";
+
+const db = new SmartDbOracle(
+  { user: "hr", password: "secret", connectString: "localhost/XEPDB1" },
+  { module: "my-app", onReady: (db, err) => { /* ... */ } }
+);
+```
+
+## Waiting for the Database
+
+All drivers signal readiness asynchronously via an RxJS `BehaviorSubject`. Use `databaseReady()` before running queries, or pass `onReady` in options.
+
+```typescript
+await db.databaseReady();
+
+// or subscribe to state changes:
+db.onReady.subscribe(state => console.log(state));
+```
+
+## Models
+
+Models map TypeScript classes to database tables. Generate them from a live schema using the CLI (see [Schema Extraction](#schema-extraction)), or write them manually:
+
+```typescript
+import { AbstractModel, ModelAttributeMap } from "@egi/smart-db";
+
+interface UserData {
+  user_id: number;
+  user_name: string;
+}
+
+class UserModel extends AbstractModel<UserModel, UserData> {
+  static readonly attributeMap: ModelAttributeMap = {
+    id:   { attribute: "_id",   alias: "user_id",   type: "number", typeScriptStyle: true },
+    name: { attribute: "_name", alias: "user_name",  type: "string", typeScriptStyle: true },
+  };
+
+  static getTableName()     { return "users"; }
+  static getPrimaryKey()    { return "user_id"; }
+  static getClassName()     { return "UserModel"; }
+  static getPkSequenceName(){ return ""; }
+  static from(other: any)   { const m = new UserModel(); m.assign(other); return m; }
+
+  private _id: number;
+  private _name: string;
+
+  get id()   { return this._id; }
+  set id(v)  { this._id = v; }
+  get name() { return this._name; }
+  set name(v){ this._name = v; }
+
+  clone()           { return UserModel.from(this); }
+  getClassName()    { return UserModel.getClassName(); }
+  getTableName()    { return UserModel.getTableName(); }
+  getPrimaryKey()   { return UserModel.getPrimaryKey(); }
+  getPkSequenceName(){ return UserModel.getPkSequenceName(); }
+  getAttributeMap() { return UserModel.attributeMap; }
+}
+```
+
+## CRUD Operations
+
+All methods have async and sync variants. Sync variants return `false` on error; async variants throw. SQLite supports both; MySQL and Oracle are async-only.
+
+### Insert
+
+```typescript
+const newId = await db.insert(UserModel, { name: "Alice" });
+const newId = db.insertSync(UserModel, { name: "Alice" }); // SQLite only
+```
+
+### Query
+
+```typescript
+// All rows
+const users = await db.getAll(UserModel);
+
+// With WHERE
+const admins = await db.getAll(UserModel, { role: "admin" });
+
+// First match
+const user = await db.getFirst(UserModel, { id: 42 });
+
+// Full options
+const results = await db.get(UserModel, {
+  where: { status: "active" },
+  orderBy: ["name asc"],
+  limit: { limit: 10, offset: 20 },
+});
+```
+
+### Update
+
+```typescript
+const affected = await db.update(UserModel, { name: "Bob" }, { id: 42 });
+```
+
+### Delete
+
+```typescript
+const deleted = await db.delete(UserModel, { id: 42 });
+```
+
+### Raw SQL
+
+```typescript
+const rows = await db.query("SELECT * FROM users WHERE id = ?", [42]);
+await db.exec("CREATE INDEX idx_name ON users(name)");
+```
+
+## WHERE Clauses
+
+WHERE conditions are plain objects. Keys are model attribute names; values can be literals or operator descriptors from `smart-db-globals`.
+
+```typescript
+import { GT, LT, IN, LIKE, IS_NULL, BETWEEN, NE } from "@egi/smart-db";
+
+// Simple equality
+const where = { status: "active" };
+
+// Operators
+const where = {
+  age:    GT(18),
+  score:  BETWEEN(80, 100),
+  name:   LIKE("%smith%"),
+  role:   IN(["admin", "editor"]),
+  deletedAt: IS_NULL(),
+};
+
+// Nested AND / OR
+const where = {
+  and: [
+    { status: "active" },
+    { or: [{ role: "admin" }, { role: "editor" }] },
+  ],
+};
+```
+
+## SQL Helper Functions
+
+Imported from `@egi/smart-db` (all re-exported from `smart-db-globals`):
+
+| Function | SQL equivalent |
+|---|---|
+| `GT(v)` | `> v` |
+| `GE(v)` | `>= v` |
+| `LT(v)` | `< v` |
+| `LE(v)` | `<= v` |
+| `NE(v)` | `!= v` |
+| `IN([...])` | `IN (...)` |
+| `NOT_IN([...])` | `NOT IN (...)` |
+| `LIKE(v)` | `LIKE v` |
+| `NOT_LIKE(v)` | `NOT LIKE v` |
+| `IS_NULL()` | `IS NULL` |
+| `IS_NOT_NULL()` | `IS NOT NULL` |
+| `BETWEEN(min, max)` | `BETWEEN min AND max` |
+| `LITERAL(expr)` | raw SQL fragment |
+| `COUNT(field?, alias?)` | `COUNT(*)` / `COUNT(field)` |
+| `SUM / MIN / MAX / AVG` | aggregate functions |
+| `COALESCE([...], alias?)` | `COALESCE(...)` |
+| `FIELD(name, alias?)` | column reference |
+| `VALUE(val, alias?)` | scalar value in SELECT |
+
+## Advanced Queries
+
+### Aggregates and Field Selection
+
+```typescript
+import { COUNT, SUM, FIELD } from "@egi/smart-db";
+
+const stats = await db.get(UserModel, {
+  fields: [COUNT("*", "total"), SUM("score", "totalScore")],
+  groupBy: "role",
+});
+```
+
+### UNION / INTERSECT / MINUS
+
+```typescript
+const results = await db.get(UserModel, {
+  where: { role: "admin" },
+  union: [{ model: UserModel, where: { role: "superadmin" } }],
+  orderBy: "name asc",
+});
+```
+
+### Distinct and Count
+
+```typescript
+const count = await db.get(UserModel, { count: true });
+const unique = await db.get(UserModel, { distinct: true, fields: "role" });
+```
+
+## Transactions
+
+```typescript
+try {
+  await db.insert(OrderModel, order);
+  await db.insert(OrderLineModel, line);
+  await db.commit();
+} catch (err) {
+  await db.rollback();
+}
+```
+
+## Schema Versioning
+
+SmartDB tracks schema versions per module. SQL upgrade scripts are picked up automatically on init:
+
+```
+sql/
+  my-app-init.sql          # Run once on first init
+  my-app-update.001.sql    # Applied in order when version is outdated
+  my-app-update.002.sql
+```
+
+Pass `sqlFilesDirectory` and `module` in options:
+
+```typescript
+new SmartDbBetterSqlite3(config, {
+  module: "my-app",
+  sqlFilesDirectory: "./sql",
+});
+```
+
+Use `skipAutoUpgrade: true` to disable automatic execution.
+
+## Schema Extraction
+
+Generate typed model files from a live database:
+
+```bash
+# SQLite
+npm run extract:sqlite:api
+
+# Oracle
+npm run extract:oracle:api
+
+# Arbitrary (via CLI)
+extract-db-api --database mydb --username user --password pass
+```
+
+## Logging
+
+```typescript
+import { SmartSeverityLevel } from "@egi/smart-db";
+
+new SmartDbBetterSqlite3(config, {
+  logOptions: {
+    level: SmartSeverityLevel.Info,
+    dbLogging: true,   // also persist logs to smart_db_log table
+  },
+  silent: true,        // suppress all console output (Fatal only)
+});
+```
+
+## Browser Usage
+
+The browser entry point exports only `AbstractModel` and `SmartDbDictionary` — no drivers, no Node.js APIs:
+
+```typescript
+import { AbstractModel } from "@egi/smart-db"; // resolves to smart-db-browser.js
+```
+
+## Date / Time Handling
+
+SmartDB applies a consistent timezone rule across all three drivers, controlled by the `dateTimeMode` option:
+
+| Mode | TIMESTAMP columns | DATE / DATETIME columns |
+|---|---|---|
+| `"rule"` *(default)* | stored as UTC | stored as local time |
+| `"utc"` | stored as UTC | stored as UTC |
+| `"local"` | stored as local time | stored as local time |
+| `"none"` | no conversion (driver default) | no conversion (driver default) |
+
+```typescript
+// Store all dates in UTC
+new SmartDbMysql(config, { dateTimeMode: "utc" });
+
+// Disable conversion entirely (e.g. when the DB session already handles it)
+new SmartDbOracle(config, { dateTimeMode: "none" });
+```
+
+The MySQL driver issues `SET time_zone = '+00:00'` on connect for `"rule"` and `"utc"` modes. For `"local"` and `"none"` it does not, preserving the server's default timezone.
+
+## Date Utilities
+
+```typescript
+import { toSmartDbDate, toSmartDbTimestamp, smartDbToDate } from "@egi/smart-db";
+
+toSmartDbDate(new Date())           // "2024-03-15 14:30:00"
+toSmartDbTimestamp(new Date())      // "2024-03-15 14:30:00.000"
+smartDbToDate("2024-03-15 14:30:00") // Date object
+```
+
+## Options Reference
+
+| Option | Type | Description |
+|---|---|---|
+| `module` | `string \| string[]` | Module name(s) for schema versioning |
+| `sqlFilesDirectory` | `string` | Directory for SQL upgrade scripts |
+| `onReady` | `(db, err?) => void` | Callback when DB reaches READY or ERROR |
+| `delayInit` | `boolean` | Skip `initDb()` in constructor; call manually |
+| `connectOnly` | `boolean` | Connect without running upgrade scripts |
+| `skipAutoUpgrade` | `boolean` | Skip schema version checks on init |
+| `smartDbDictionary` | `typeof SmartDbDictionary` | Register model dictionaries |
+| `silent` | `boolean` | Suppress all logging below Fatal |
+| `needsExplicitEscape` | `boolean` | Enable explicit escaping (Oracle) |
+| `dateTimeMode` | `SmartDbDateTimeMode` | Date/time timezone rule — see [Date / Time Handling](#date--time-handling) |
+| `logOptions` | `SmartLogOptions` | Logging configuration |

package/assets/mysql/smart-db-core-update.001.sql

@@ -0,0 +1,10 @@
+drop table smart_db_core_table;
+
+update smart_db_version
+   set ver_sequence = 1,
+       ver_version = '2',
+       ver_sub_version = '0',
+       ver_revision = '0',
+       ver_release_type = null
+ where ver_module = 'smart-db-core';
+

package/assets/oracle/smart-db-core-update.001.sql

@@ -0,0 +1,13 @@
+drop sequence smart_db_core_table_seq;
+drop trigger smart_db_core_table_ins;
+drop table smart_db_core_table;
+drop view smart_db_user_tab_columns_view;
+
+update smart_db_version
+   set ver_sequence = 1,
+       ver_version = '2',
+       ver_sub_version = '0',
+       ver_revision = '0',
+       ver_release_type = null
+ where ver_module = 'smart-db-core';
+

package/assets/sqlite3/smart-db-core-update.001.sql

@@ -0,0 +1,10 @@
+drop table if exists smart_db_core_table;
+
+update smart_db_version
+   set ver_sequence = 1,
+       ver_version = '2',
+       ver_sub_version = '0',
+       ver_revision = '0',
+       ver_release_type = null
+ where ver_module = 'smart-db-core';
+

package/drivers/smart-db-better-sqlite3.d.ts

@@ -1,31 +1,118 @@
-import BetterSqlite3 from "better-sqlite3";
+import * as BetterSqlite3 from "better-sqlite3";
 import { AbstractModel } from "../models/abstract-model";
 import { SmartDb } from "../smart-db";
-import { GenericModelData, SmartDbRunResult, SmartDbTableInfo } from "../smart-db-interfaces";
+import { GenericModelData, ModelClass, SmartDbOptions, SmartDbRunResult, SmartDbTableInfo, SqlValueType } from "../smart-db-interfaces";
 import { SmartDbSqlBuildData } from "../smart-db-sql-build-data";
-declare type VariableArgFunction = (...params: any[]) => any;
-export declare class SmartDbBetterSqlite3 extends SmartDb {
-    protected db: BetterSqlite3.Database;
-    constructor(connectorOrDb: string | BetterSqlite3.Database, options?: BetterSqlite3.Options);
+type VariableArgFunction = (...params: any[]) => any;
+export type SmartDbBetterSqlite3Options = SmartDbOptions<SmartDbBetterSqlite3>;
+/** Configuration for {@link SmartDbBetterSqlite3}. Extends the better-sqlite3 `Options` with a required `filename`. */
+interface BetterSqlite3Config extends BetterSqlite3.Options {
+    /** Path to the SQLite database file, or `":memory:"` for an in-memory database. */
+    filename: string;
+}
+/**
+ * SmartDB driver for SQLite via the `better-sqlite3` library.
+ *
+ * This is the only driver that supports **synchronous** operations (`getSync`, `insertSync`, etc.)
+ * in addition to the standard async API. The connection is opened synchronously in the constructor
+ * and the database transitions to `CONNECTED` before `initDb()` runs.
+ *
+ * @example
+ * ```ts
+ * const db = new SmartDbBetterSqlite3(
+ *   { filename: "./my.db" },
+ *   { module: "my-app", sqlFilesDirectory: "./sql", onReady: (db, err) => { ... } }
+ * );
+ * await db.databaseReady();
+ * ```
+ */
+export declare class SmartDbBetterSqlite3 extends SmartDb<SmartDbBetterSqlite3> {
+    /**
+     * Opens the SQLite database file and transitions to `CONNECTED` synchronously.
+     * `initDb()` is called immediately afterwards (unless `delayInit: true` is set),
+     * running any pending schema upgrade scripts before the state reaches `READY`.
+     *
+     * @param config - Database file path and better-sqlite3 open options.
+     * @param options - SmartDB options (module, SQL directory, callbacks, etc.).
+     */
+    constructor(config: BetterSqlite3Config, options?: SmartDbBetterSqlite3Options);
+    /**
+     * Registers a custom aggregate function with the SQLite connection.
+     * Delegates directly to `better-sqlite3` `Database.aggregate()`.
+     *
+     * @param name - Name of the aggregate function as it will appear in SQL.
+     * @param options - Step/result callbacks and options passed to better-sqlite3.
+     * @returns `true` on success, `false` if an error occurred (check {@link getLastError}).
+     */
     aggregate(name: string, options: BetterSqlite3.AggregateOptions): boolean;
+    /**
+     * Creates an online backup of the database to `destinationFile`.
+     * Delegates to `better-sqlite3` `Database.backup()` and wraps the result in a Promise.
+     *
+     * @param destinationFile - Path to the destination backup file.
+     * @param options - Optional better-sqlite3 backup options (e.g. progress callback, rate).
+     * @returns Resolves with backup metadata on success, rejects with the last error on failure.
+     */
     backup(destinationFile: string, options?: BetterSqlite3.BackupOptions): Promise<BetterSqlite3.BackupMetadata>;
-    closeSync(): boolean;
-    commitSync(): void;
+    /**
+     * Toggles safe-integer mode for the connection. When enabled, 64-bit integers are
+     * returned as `BigInt` instead of `number` to avoid precision loss.
+     *
+     * @param toggleState - `true` to enable, `false` to disable. Omit to read the current state.
+     * @returns `true` on success, `false` if an error occurred.
+     */
     defaultSafeIntegers(toggleState?: boolean): boolean;
-    execSync(script: string): boolean;
-    existsSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), type?: "view" | "table" | "index", indexTableName?: string): boolean;
+    /**
+     * Registers a custom scalar function with the SQLite connection.
+     * The callback receives SQL argument values and returns the result.
+     *
+     * @param name - Name of the function as it will appear in SQL.
+     * @param options - Registration options (deterministic, varargs, etc.) or the callback directly.
+     * @param cb - The function implementation (only required when `options` is not a function).
+     * @returns `true` on success, `false` if an error occurred.
+     */
     func(name: string, options: BetterSqlite3.RegistrationOptions, cb: VariableArgFunction): boolean;
     getDatabaseType(): string;
     getTableInfo(tableName: string): Promise<SmartDbTableInfo>;
+    getDb(): BetterSqlite3.Database;
+    protected db: BetterSqlite3.Database;
+    get supportSyncCalls(): boolean;
+    closeSync(): boolean;
+    commitSync(): void;
+    execSync(script: string, params?: SqlValueType[]): boolean;
+    querySync(script: string, params?: SqlValueType[]): GenericModelData[];
+    existsSync<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, type?: "view" | "table" | "index", indexTableName?: string): boolean;
     hasTransaction(): boolean;
-    loadExtension(path: string): boolean;
-    pragma(source: string, options?: BetterSqlite3.PragmaOptions): unknown;
     rollbackSync(): void;
-    transaction<F extends VariableArgFunction>(fn: F): boolean;
+    protected statementGetAllSync(buildData: SmartDbSqlBuildData): any[];
+    protected statementGetSync(buildData: SmartDbSqlBuildData): unknown;
     protected statementRun(buildData: SmartDbSqlBuildData, retry?: number): Promise<SmartDbRunResult>;
     protected statementRunSync(buildData: SmartDbSqlBuildData): SmartDbRunResult;
-    protected statementGetSync(buildData: SmartDbSqlBuildData): any;
-    protected statementGetAllSync(buildData: SmartDbSqlBuildData): any[];
-    get supportSyncCalls(): boolean;
+    /**
+     * Loads a compiled SQLite extension from the given shared-library path.
+     *
+     * @param path - Filesystem path to the `.so` / `.dylib` / `.dll` extension file.
+     * @returns `true` on success, `false` if loading failed (check {@link getLastError}).
+     */
+    loadExtension(path: string): boolean;
+    /**
+     * Executes a SQLite PRAGMA statement and returns the result.
+     *
+     * @param source - The PRAGMA expression, e.g. `"journal_mode = WAL"` or `"table_info(users)"`.
+     * @param options - Optional better-sqlite3 pragma options (e.g. `simple: true` to return a scalar).
+     * @returns The pragma result, or `false` if an error occurred.
+     */
+    pragma(source: string, options?: BetterSqlite3.PragmaOptions): unknown;
+    /**
+     * Wraps a function in a better-sqlite3 transaction and registers it with the connection.
+     * The returned transaction function can be called multiple times; each call runs atomically.
+     * For a simple one-shot transaction use `beginTransaction()` / `commitSync()` / `rollbackSync()`.
+     *
+     * @param fn - The function to wrap. Receives the same arguments passed to the transaction function.
+     * @returns `true` on success, `false` if registration failed.
+     */
+    transaction<F extends VariableArgFunction>(fn: F): boolean;
+    /** Begins an explicit transaction by executing `BEGIN TRANSACTION`. */
+    beginTransaction(): void;
 }
 export {};

package/drivers/smart-db-better-sqlite3.js

@@ -1 +1 @@
-import BetterSqlite3 from"better-sqlite3";import _ from"lodash";import{SqliteMasterModel}from"../models/sqlite-master-model";import{SmartDb}from"../smart-db";export class SmartDbBetterSqlite3 extends SmartDb{constructor(t,e){_.isString(t)?(super(t),this.db=new BetterSqlite3(t,e)):(super(null),this.db=t,this.db.inTransaction),this.isReady=!0}aggregate(t,e){return!!this.saveExecute((()=>this.db.aggregate(t,e)))}backup(t,e){return new Promise(((s,r)=>{const n=this.saveExecute((()=>this.db.backup(t,e)));0==n?r(this.getLastError()):s(n)}))}closeSync(){return this.smartDbLog.setDb(null),this.isReady=!1,!!this.db.close()}commitSync(){this.db.inTransaction&&this.db.exec("commit")}defaultSafeIntegers(t){return!!this.saveExecute((()=>this.db.defaultSafeIntegers(t)))}execSync(t){return!!this.saveExecute((()=>this.db.exec(t)))}existsSync(t,e,s){let r=!1;const n=_.isString(t)?t:t.getTableName(),a=this.getFirstSync(SqliteMasterModel,{name:n,type:e,tblName:s});if(!1===a)throw this.getLastError();return r=!!a,r}func(t,e,s){return this.saveExecute((()=>{let r;return r=_.isFunction(e)?this.db.function(t,e):this.db.function(t,e,s),r}))}getDatabaseType(){return"sqlite3"}getTableInfo(t){return new Promise((e=>{const s=this.pragma(`table_info(${t})`);let r=[];s&&(r=s.map((t=>({cid:t.cid,name:t.name,type:t.type,notNull:0!==t.notnull,defaultValue:t.dflt_value,isPk:0!==t.pk}))),e({name:t,fields:r}))}))}hasTransaction(){return this.db.inTransaction}loadExtension(t){return!!this.saveExecute((()=>this.db.loadExtension(t)))}pragma(t,e){return this.saveExecute((()=>this.db.pragma(t,e)))}rollbackSync(){this.db.inTransaction&&this.db.exec("rollback")}transaction(t){return!!this.saveExecute((()=>this.db.transaction(t)))}statementRun(t,e=0){return new Promise(((s,r)=>{try{s(this.statementRunSync(t))}catch(n){"SQLITE_BUSY"==n.code&&e<10?setTimeout((()=>{this.statementRun(t,e+1).then((t=>{s(t)})).catch((t=>{r(t)}))}),100):(this.lastError=n,r(n))}}))}statementRunSync(t){const e=this.db.prepare(t.sql),s=e&&e.run(t.values);return s&&{changes:s.changes,affected:s.changes,lastId:s.lastInsertRowid}}statementGetSync(t){const e=this.db.prepare(t.sql);return e&&e.get(t.values)}statementGetAllSync(t){const e=this.db.prepare(t.sql);return e&&e.all(t.values)}get supportSyncCalls(){return!0}}
+"use strict";var __extends=this&&this.__extends||function(){var t=function(e,r){return t=Object.setPrototypeOf||{__proto__:[]}instanceof Array&&function(t,e){t.__proto__=e}||function(t,e){for(var r in e)Object.prototype.hasOwnProperty.call(e,r)&&(t[r]=e[r])},t(e,r)};return function(e,r){if("function"!=typeof r&&null!==r)throw new TypeError("Class extends value "+String(r)+" is not a constructor or null");function n(){this.constructor=e}t(e,r),e.prototype=null===r?Object.create(r):(n.prototype=r.prototype,new n)}}();Object.defineProperty(exports,"__esModule",{value:!0}),exports.SmartDbBetterSqlite3=void 0;var BetterSqlite3=require("better-sqlite3"),sqlite_master_model_1=require("../models/sqlite-master-model"),smart_db_1=require("../smart-db"),smart_db_interfaces_1=require("../smart-db-interfaces"),SmartDbBetterSqlite3=function(t){function e(e,r){var n=t.call(this,e.filename,r)||this;return n.readyState=smart_db_interfaces_1.SmartDbReadyState.PREPARING,n.db=new BetterSqlite3(e.filename,e),n.readyState=smart_db_interfaces_1.SmartDbReadyState.CONNECTED,n}return __extends(e,t),e.prototype.aggregate=function(t,e){var r=this;return!!this.saveExecute(function(){return r.db.aggregate(t,e)})},e.prototype.backup=function(t,e){var r=this;return new Promise(function(n,o){var a=r.saveExecute(function(){return r.db.backup(t,e)});0==a?o(r.getLastError()):n(a)})},e.prototype.defaultSafeIntegers=function(t){var e=this;return!!this.saveExecute(function(){return e.db.defaultSafeIntegers(t)})},e.prototype.func=function(t,e,r){var n=this;return this.saveExecute(function(){return!!("function"==typeof e?n.db.function(t,e):n.db.function(t,e,r))})},e.prototype.getDatabaseType=function(){return"sqlite3"},e.prototype.getTableInfo=function(t){var e=this;return new Promise(function(r,n){var o=e.pragma("table_info(".concat(t,")")),a=[];o?(a=o.map(function(t){var e=t.type.toUpperCase(),r=e.match(/^([^(]+)/);return{cid:t.cid,name:t.name,dbType:r?r[1]:e,dbFullType:e,notNull:0!==t.notnull,defaultValue:t.dflt_value,isPk:0!==t.pk}}),r({name:t,fields:a})):n("no such table '".concat(t,"'"))})},e.prototype.getDb=function(){return this.db},Object.defineProperty(e.prototype,"supportSyncCalls",{get:function(){return!0},enumerable:!1,configurable:!0}),e.prototype.closeSync=function(){return this.log.setDbWriter(null),this.readyState=smart_db_interfaces_1.SmartDbReadyState.CLOSED,!!this.db.close()},e.prototype.commitSync=function(){this.db.inTransaction&&this.db.exec("commit")},e.prototype.execSync=function(t,e){var r=this;return!!this.saveExecute(function(){return e&&e.length>0?r.db.prepare(t).run(e):r.db.exec(t)})},e.prototype.querySync=function(t,e){var r=this;return this.saveExecute(function(){var n=r.db.prepare(t);return n&&n.all(null!=e?e:[])})},e.prototype.existsSync=function(t,e,r){var n="string"==typeof t?t:t.getTableName(),o=this.getFirstSync(sqlite_master_model_1.SqliteMasterModel,{name:n,type:e,tblName:r});if(!1===o)throw this.getLastError();return!!o},e.prototype.hasTransaction=function(){return this.db.inTransaction},e.prototype.rollbackSync=function(){this.db.inTransaction&&this.db.exec("rollback")},e.prototype.statementGetAllSync=function(t){var e=this.db.prepare(t.sql);return e&&e.all(t.values)},e.prototype.statementGetSync=function(t){var e=this.db.prepare(t.sql);return e&&e.get(t.values)},e.prototype.statementRun=function(t,e){var r=this;return void 0===e&&(e=0),new Promise(function(n,o){try{n(r.statementRunSync(t))}catch(a){"SQLITE_BUSY"==a.code&&e<10?setTimeout(function(){r.statementRun(t,e+1).then(function(t){n(t)}).catch(function(t){o(t)})},100):(r.lastError=a,o(a))}})},e.prototype.statementRunSync=function(t){var e=this.db.prepare(t.sql),r=e&&e.run(t.values);return r&&{changes:r.changes,affected:r.changes,lastId:r.lastInsertRowid}},e.prototype.loadExtension=function(t){var e=this;return!!this.saveExecute(function(){return e.db.loadExtension(t)})},e.prototype.pragma=function(t,e){var r=this;return this.saveExecute(function(){return r.db.pragma(t,e)})},e.prototype.transaction=function(t){var e=this;return!!this.saveExecute(function(){return e.db.transaction(t)})},e.prototype.beginTransaction=function(){this.db.exec("begin transaction")},e}(smart_db_1.SmartDb);exports.SmartDbBetterSqlite3=SmartDbBetterSqlite3;

package/drivers/smart-db-mysql.d.ts

@@ -1,20 +1,63 @@
-import Mysql, { Connection, ConnectionConfig } from "mysql";
+import * as Mysql from "mysql2";
+import { ConnectionOptions } from "mysql2";
 import { AbstractModel } from "../models/abstract-model";
 import { SmartDb } from "../smart-db";
-import { GenericModelData, SmartDbRunResult, SmartDbTableInfo } from "../smart-db-interfaces";
+import { GenericModelData, ModelClass, SmartDbOptions, SmartDbRunResult, SmartDbTableInfo, SqlValueType } from "../smart-db-interfaces";
 import { SmartDbSqlBuildData } from "../smart-db-sql-build-data";
-export declare class SmartDbMysql extends SmartDb {
+export type SmartDbMysqlOptions = SmartDbOptions<SmartDbMysql>;
+/**
+ * SmartDB driver for MySQL / MariaDB via the `mysql2` library.
+ *
+ * All operations are **async-only** — there are no sync variants.
+ * The constructor creates the connection and, for `"rule"` and `"utc"` date-time modes,
+ * immediately issues `SET time_zone = '+00:00'` so that all timestamps are stored and
+ * retrieved in UTC. The ready-state transitions to `CONNECTED` once that query completes.
+ *
+ * @example
+ * ```ts
+ * const db = new SmartDbMysql(
+ *   { host: "localhost", user: "root", password: "secret", database: "mydb" },
+ *   { module: "my-app", sqlFilesDirectory: "./sql", onReady: (db, err) => { ... } }
+ * );
+ * await db.databaseReady();
+ * ```
+ */
+export declare class SmartDbMysql extends SmartDb<SmartDbMysql> {
+    /**
+     * Creates a mysql2 connection and transitions to `CONNECTED`.
+     * For `dateTimeMode` `"rule"` (default) and `"utc"`, `SET time_zone = '+00:00'` is issued
+     * before `CONNECTED` is set; an error during that query puts the instance into `ERROR` state.
+     *
+     * @param config - mysql2 `ConnectionOptions` (host, user, password, database, port, etc.).
+     * @param options - SmartDB options (module, SQL directory, dateTimeMode, callbacks, etc.).
+     */
+    constructor(config: ConnectionOptions, options?: SmartDbMysqlOptions);
+    getDatabaseType(): string;
+    getTableInfo(tableName: string): Promise<SmartDbTableInfo>;
+    getDb(): Mysql.Connection;
     protected db: Mysql.Connection;
-    constructor(connectorOrDb: string | ConnectionConfig | Connection);
-    close(): Promise<boolean>;
     commit(): Promise<void>;
-    exec(script: string): Promise<void>;
-    exists<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | (new () => T), type?: "view" | "table" | "index", indexTableName?: string): Promise<boolean>;
-    getDatabaseType(): string;
+    exec(script: string, params?: SqlValueType[]): Promise<void>;
+    query(script: string, params?: SqlValueType[]): Promise<GenericModelData[]>;
+    exists<T extends AbstractModel<T, D>, D extends GenericModelData>(modelClass: string | ModelClass<T>, type?: "view" | "table" | "index", indexTableName?: string): Promise<boolean>;
     getDbQuote(): string;
-    getTableInfo(tableName: string): Promise<SmartDbTableInfo>;
     rollback(): Promise<void>;
-    protected statementRun(buildData: SmartDbSqlBuildData): Promise<SmartDbRunResult>;
     protected statementGet<T extends object>(buildData: SmartDbSqlBuildData): Promise<T>;
     protected statementGetAll<T>(buildData: SmartDbSqlBuildData): Promise<T[]>;
+    protected statementRun(buildData: SmartDbSqlBuildData): Promise<SmartDbRunResult>;
+    /**
+     * mysql2 interprets date strings returned by MySQL (in UTC due to `SET time_zone = '+00:00'`) as local
+     * time, introducing an offset equal to the local timezone. This method removes that offset, restoring the
+     * intended UTC value — mirroring the same correction applied in the Oracle driver.
+     * Which column types are corrected depends on `dateTimeMode`:
+     * - `"rule"` — only TIMESTAMP columns (wire type 7); DATE / DATETIME are in local time intentionally.
+     * - `"utc"` — TIMESTAMP (7), DATE (10), and DATETIME (12); all were written as UTC.
+     * - `"local"` / `"none"` — no correction applied.
+     *
+     * @param rows
+     * @param fields
+     * @private
+     */
+    private adjustResultTimestamps;
+    close(): Promise<boolean>;
 }

package/drivers/smart-db-mysql.js

@@ -1 +1 @@
-import _ from"lodash";import Mysql from"mysql";import{SmartDb}from"../smart-db";export class SmartDbMysql extends SmartDb{constructor(t){t.config&&t.connect?(super(t.config),this.db=t):(super(t),this.db=Mysql.createConnection(t))}close(){return new Promise((t=>{this.db.end((r=>{this.isReady=!1,r?(this.lastError=r,t(!1)):t(!0)}))}))}commit(){return new Promise(((t,r)=>{this.db.commit((e=>{e?(this.lastError=e,r(e)):t()}))}))}exec(t){return new Promise(((r,e)=>{try{this.db.query(t,((t,s,o)=>{t?(this.lastError=t,e(t)):r()}))}catch(t){this.lastError=t,e(t)}}))}exists(t,r,e){return new Promise(((r,e)=>{const s=_.isString(t)?t:t.getTableName();this.db.query(`show tables like '${s}'`,((t,s,o)=>{t?(this.lastError=t,e(t)):r(s&&s.length>0)}))}))}getDatabaseType(){return"mysql"}getDbQuote(){return"`"}getTableInfo(t){throw new Error("Method not implemented (getTableInfo)")}rollback(){return new Promise(((t,r)=>{this.db.rollback((e=>{e?(this.lastError=e,r(e)):t()}))}))}statementRun(t){return new Promise(((r,e)=>{this.db.query(t.sql,t.values,((t,s,o)=>{if(t)this.lastError=t,e(t);else{const t={changes:s.changedRows,affected:s.affectedRows,lastId:s.insertId};r(t)}}))}))}statementGet(t){return new Promise(((r,e)=>{try{this.db.query(t.sql,t.values,((t,s,o)=>{t?(this.lastError=t,e(t)):r(s&&s[0])}))}catch(t){this.lastError=t,e(t)}}))}statementGetAll(t){return new Promise(((r,e)=>{this.db.query(t.sql,t.values,((t,s,o)=>{t?(this.lastError=t,e(t)):r(s&&s)}))}))}}
+"use strict";var __extends=this&&this.__extends||function(){var t=function(e,r){return t=Object.setPrototypeOf||{__proto__:[]}instanceof Array&&function(t,e){t.__proto__=e}||function(t,e){for(var r in e)Object.prototype.hasOwnProperty.call(e,r)&&(t[r]=e[r])},t(e,r)};return function(e,r){if("function"!=typeof r&&null!==r)throw new TypeError("Class extends value "+String(r)+" is not a constructor or null");function n(){this.constructor=e}t(e,r),e.prototype=null===r?Object.create(r):(n.prototype=r.prototype,new n)}}(),__awaiter=this&&this.__awaiter||function(t,e,r,n){return new(r||(r=Promise))(function(o,a){function i(t){try{s(n.next(t))}catch(t){a(t)}}function u(t){try{s(n.throw(t))}catch(t){a(t)}}function s(t){var e;t.done?o(t.value):(e=t.value,e instanceof r?e:new r(function(t){t(e)})).then(i,u)}s((n=n.apply(t,e||[])).next())})},__generator=this&&this.__generator||function(t,e){var r,n,o,a={label:0,sent:function(){if(1&o[0])throw o[1];return o[1]},trys:[],ops:[]},i=Object.create(("function"==typeof Iterator?Iterator:Object).prototype);return i.next=u(0),i.throw=u(1),i.return=u(2),"function"==typeof Symbol&&(i[Symbol.iterator]=function(){return this}),i;function u(u){return function(s){return function(u){if(r)throw new TypeError("Generator is already executing.");for(;i&&(i=0,u[0]&&(a=0)),a;)try{if(r=1,n&&(o=2&u[0]?n.return:u[0]?n.throw||((o=n.return)&&o.call(n),0):n.next)&&!(o=o.call(n,u[1])).done)return o;switch(n=0,o&&(u=[2&u[0],o.value]),u[0]){case 0:case 1:o=u;break;case 4:return a.label++,{value:u[1],done:!1};case 5:a.label++,n=u[1],u=[0];continue;case 7:u=a.ops.pop(),a.trys.pop();continue;default:if(!(o=a.trys,(o=o.length>0&&o[o.length-1])||6!==u[0]&&2!==u[0])){a=0;continue}if(3===u[0]&&(!o||u[1]>o[0]&&u[1]<o[3])){a.label=u[1];break}if(6===u[0]&&a.label<o[1]){a.label=o[1],o=u;break}if(o&&a.label<o[2]){a.label=o[2],a.ops.push(u);break}o[2]&&a.ops.pop(),a.trys.pop();continue}u=e.call(t,a)}catch(t){u=[6,t],n=0}finally{r=o=0}if(5&u[0])throw u[1];return{value:u[0]?u[1]:void 0,done:!0}}([u,s])}}};Object.defineProperty(exports,"__esModule",{value:!0}),exports.SmartDbMysql=void 0;var Mysql=require("mysql2"),smart_db_1=require("../smart-db"),smart_db_interfaces_1=require("../smart-db-interfaces"),SmartDbMysql=function(t){function e(e,r){var n,o,a=this,i=e.user+"@"+e.host+":"+(null!==(n=e.port)&&void 0!==n?n:3306);e.database&&e.database!=e.user&&(i+="/"+e.database),(a=t.call(this,i,r)||this).readyState=smart_db_interfaces_1.SmartDbReadyState.PREPARING,a.db=Mysql.createConnection(e);var u=null!==(o=null==r?void 0:r.dateTimeMode)&&void 0!==o?o:"rule";return"rule"==u||"utc"==u?a.db.query("SET time_zone = '+00:00'",function(t){t?(a.lastError=t,a.readyState=smart_db_interfaces_1.SmartDbReadyState.ERROR):a.readyState=smart_db_interfaces_1.SmartDbReadyState.CONNECTED}):a.readyState=smart_db_interfaces_1.SmartDbReadyState.CONNECTED,a}return __extends(e,t),e.prototype.getDatabaseType=function(){return"mysql"},e.prototype.getTableInfo=function(t){var e=this;return new Promise(function(r,n){e.db.query({sql:"describe ".concat(t)},function(o,a){if(o)e.lastError=o,n(o);else{var i=[];a&&(i=a.map(function(t,e){var r=t.Type.toUpperCase(),n=r.match(/^([^(]+)/);return{cid:e,name:t.Field,dbType:n?n[1]:r,dbFullType:r,notNull:"NO"==t.Null,defaultValue:t.Default,isPk:"PRI"==t.Key}})),r({name:t,fields:i})}})})},e.prototype.getDb=function(){return this.db},e.prototype.commit=function(){var t=this;return new Promise(function(e,r){t.db.commit(function(n){n?(t.lastError=n,r(n)):e()})})},e.prototype.exec=function(t,e){return __awaiter(this,void 0,void 0,function(){var r=this;return __generator(this,function(n){return[2,new Promise(function(n,o){try{r.db.query(t,null!=e?e:[],function(t,e,a){t?(r.lastError=t,o(t)):n()})}catch(t){r.lastError=t,o(t)}})]})})},e.prototype.query=function(t,e){return __awaiter(this,void 0,void 0,function(){var r=this;return __generator(this,function(n){return[2,new Promise(function(n,o){try{r.db.query(t,null!=e?e:[],function(t,e){t?(r.lastError=t,o(t)):n(e)})}catch(t){r.lastError=t,o(t)}})]})})},e.prototype.exists=function(t,e,r){var n=this;return new Promise(function(e,r){var o="string"==typeof t?t:t.getTableName();n.db.query("show tables like '".concat(o,"'"),function(t,o,a){t?(n.lastError=t,r(t)):e(o&&o.length>0)})})},e.prototype.getDbQuote=function(){return"`"},e.prototype.rollback=function(){var t=this;return new Promise(function(e,r){try{t.db.rollback(function(){e()})}catch(t){r(t)}})},e.prototype.statementGet=function(t){var e=this;return new Promise(function(r,n){try{e.db.query(t.sql,t.values,function(t,o,a){t?(e.lastError=t,n(t)):(e.adjustResultTimestamps(o,a),r(o&&o[0]))})}catch(t){e.lastError=t,n(t)}})},e.prototype.statementGetAll=function(t){var e=this;return new Promise(function(r,n){e.db.query(t.sql,t.values,function(t,o,a){t?(e.lastError=t,n(t)):(e.adjustResultTimestamps(o,a),r(o))})})},e.prototype.statementRun=function(t){var e=this;return new Promise(function(r,n){e.db.query(t.sql,t.values,function(t,o,a){if(t)e.lastError=t,n(t);else{var i=o,u={changes:i.affectedRows,affected:i.affectedRows,lastId:i.insertId};r(u)}})})},e.prototype.adjustResultTimestamps=function(t,e){var r,n=null!==(r=this.options.dateTimeMode)&&void 0!==r?r:"rule";if(t&&e&&("rule"==n||"utc"==n)){var o="utc"==n?[7,10,12]:[7],a=e.filter(function(t){return o.includes(t.type)}).map(function(t){return t.name});a.length>0&&t.forEach(function(t){a.forEach(function(e){var r=t[e];r instanceof Date&&(t[e]=new Date(r.getTime()-6e4*r.getTimezoneOffset()))})})}},e.prototype.close=function(){var t=this;return new Promise(function(e){t.db.end(function(r){t.readyState=smart_db_interfaces_1.SmartDbReadyState.CLOSED,r?(t.lastError=r,e(!1)):e(!0)})})},e}(smart_db_1.SmartDb);exports.SmartDbMysql=SmartDbMysql;