stabilize-orm 1.1.3 → 1.1.5

package/client.ts

@@ -1,233 +1,216 @@
-import { sql, SQL } from "bun";
+/**
+ * @file client.ts
+ * @description Provides a unified database client for interacting with PostgreSQL, MySQL, and SQLite.
+ * @author ElectronSz
+ */
+
 import { Database, Statement } from "bun:sqlite";
+import { Pool, type PoolClient } from "pg";
+import mysql from "mysql2/promise";
 import {
   type DBConfig,
   StabilizeError,
-  type PoolMetrics,
   DBType,
 } from "./types";
 import { type Logger, ConsoleLogger } from "./logger";
 
+/** @internal Checks if the config is for SQLite. */
 function isSQLiteConfig(config: DBConfig): boolean {
-  return (
-    config.type === DBType.SQLite || config.connectionString.includes("sqlite")
-  );
+  return config.type === DBType.SQLite;
+}
+
+/** @internal Checks if the config is for MySQL. */
+function isMySQLConfig(config: DBConfig): boolean {
+  return config.type === DBType.MySQL;
 }
 
+/** @internal A type guard to reliably identify a mysql2 Pool object. */
+function isMySQLPool(client: any): client is mysql.Pool {
+  return typeof client.getConnection === 'function';
+}
+
+/**
+ * A unified database client that provides a consistent interface for
+ * PostgreSQL, MySQL, and SQLite databases. It handles connection pooling,
+ * query execution with retries, and transactions.
+ */
 export class DBClient {
-  private client: Database | any | null = null;
+  private client!: Database | Pool | mysql.Pool | PoolClient | mysql.PoolConnection;
   private logger: Logger;
+  public readonly config: DBConfig; 
   private retryAttempts: number;
   private retryDelay: number;
   private maxJitter: number;
 
   private preparedStatements: Map<string, Statement> = new Map();
-  private config: DBConfig;
-
-  constructor(config: DBConfig, logger: Logger = new ConsoleLogger()) {
+  public readonly isTransactionClient: boolean = false;
+
+  /**
+   * Creates an instance of DBClient.
+   * @param config The database configuration object.
+   * @param logger A logger instance for logging messages.
+   * @param existingClient An optional existing connection, used internally for transactions.
+   */
+  constructor(
+    config: DBConfig,
+    logger: Logger = new ConsoleLogger(),
+    existingClient: PoolClient | mysql.PoolConnection | null = null,
+  ) {
     this.config = config;
     this.logger = logger;
     this.retryAttempts = config.retryAttempts || 3;
     this.retryDelay = config.retryDelay || 1000;
     this.maxJitter = config.maxJitter || 100;
 
-    this.initializeClient(config);
+    if (existingClient) {
+      this.client = existingClient;
+      this.isTransactionClient = true;
+    } else {
+      this.initializeClient(config);
+    }
   }
 
+  /**
+   * @internal
+   * Initializes the database client based on the provided configuration.
+   * @param config The database configuration.
+   */
   private initializeClient(config: DBConfig) {
     if (isSQLiteConfig(config)) {
-      try {
-        // new Database(path, { create: true }) is the standard Bun method
-        this.client = new Database(config.connectionString, { create: true });
-        this.logger.logDebug(
-          `Initialized Bun SQLite client for: ${config.connectionString}`,
-        );
-      } catch (e) {
-        this.logger.logError(e as Error);
-        throw new StabilizeError(
-          `Failed to initialize SQLite database: ${(e as Error).message}`,
-          "INIT_ERROR",
-        );
-      }
-    } else {
-      this.client = new SQL(config.connectionString);
-      this.logger.logDebug(
-        `Initialized Bun SQL client for: ${config.connectionString}`,
-      );
+      this.client = new Database(config.connectionString, { create: true });
+      this.logger.logDebug(`Initialized Bun SQLite client.`);
+    } else if (isMySQLConfig(config)) {
+      this.client = mysql.createPool(config.connectionString);
+      this.logger.logDebug(`Initialized MySQL Pool client.`);
+    } else { 
+      this.client = new Pool({ connectionString: config.connectionString });
+      this.logger.logDebug(`Initialized Postgres Pool client.`);
     }
   }
-
-  private getJitter() {
-    return Math.random() * this.maxJitter;
-  }
-
-  getPoolMetrics(): PoolMetrics {
-    return {
-      activeConnections: 0,
-      idleConnections: 0,
-      totalConnections: this.client instanceof Database ? 1 : 0,
-    };
-  }
-
-  async switchConnection(config: DBConfig) {
-    await this.close();
-    this.config = config;
-    this.preparedStatements.clear();
-    this.retryAttempts = config.retryAttempts || 3;
-    this.retryDelay = config.retryDelay || 1000;
-    this.maxJitter = config.maxJitter || 100;
-    this.initializeClient(config);
-  }
-
+  
+  /** @internal Gets a random jitter value to add to retry delays. */
+  private getJitter = () => Math.random() * this.maxJitter;
+
+  /**
+   * Executes a SQL query with parameters and returns the result.
+   * Automatically handles placeholder conversion for different databases and includes retry logic.
+   * @template T The expected type of the result rows.
+   * @param query The SQL query string with `?` as placeholders.
+   * @param params An array of parameters to bind to the query.
+   * @returns A promise that resolves to an array of results.
+   * @example
+   * ```
+   * const users = await dbClient.query('SELECT * FROM users WHERE status = ?', ['active']);
+   * ```
+   */
   async query<T>(query: string, params: any[] = []): Promise<T[]> {
     const start = Date.now();
     this.logger.logQuery(query, params);
-    this.logger.logMetrics(this.getPoolMetrics());
-
-    let stmt: Statement | undefined;
-
-    // Check for Bun SQLite client
-    if (this.client instanceof Database) {
-      const stmtKey = query;
-      // Use prepared statement caching for SQLite
-      if (!this.preparedStatements.has(stmtKey)) {
-        // Use this.client (the Database instance) to prepare the statement
-        this.preparedStatements.set(stmtKey, this.client.prepare(query));
-      }
-      stmt = this.preparedStatements.get(stmtKey);
-    }
 
     for (let attempt = 1; attempt <= this.retryAttempts; attempt++) {
       try {
-        let result: T[];
-
-        if (stmt) {
-          result = stmt.all(...params) as T[];
-        } else if (this.client) {
-              result = (await (this.client as any).unsafe(query, params)) as T[];
-        } else {
-          throw new StabilizeError(
-            "Database client is not initialized or does not support query execution.",
-            "INIT_ERROR",
-          );
+        let result: any;
+
+        if (this.client instanceof Database) { // SQLite
+          let stmt = this.preparedStatements.get(query);
+          if (!stmt) {
+            stmt = this.client.prepare(query);
+            this.preparedStatements.set(query, stmt);
+          }
+          result = stmt.all(...params);
+        } else if (isMySQLPool(this.client) || ('query' in this.client && 'release' in this.client)) { // mysql2 Pool or Connection
+            const [rows] = await (this.client as mysql.Pool).query(query, params);
+            result = rows;
+        } else { // Postgres Pool or Client
+          const pgQuery = query.replace(/\?/g, (_, i) => `$${i + 1}`);
+          const pgResult = await (this.client as Pool).query(pgQuery, params);
+          result = pgResult.rows;
         }
 
         const executionTime = Date.now() - start;
         this.logger.logQuery(query, params, executionTime);
-        return result;
+        return result as T[];
       } catch (error) {
         this.logger.logError(error as Error);
-        if (attempt === this.retryAttempts) {
-          throw new StabilizeError(
-            `Query failed after ${this.retryAttempts} attempts: ${(error as Error).message}`,
-            "QUERY_ERROR",
-          );
-        }
-        await new Promise((resolve) =>
-          setTimeout(
-            resolve,
-            this.retryDelay * Math.pow(2, attempt - 1) + this.getJitter(),
-          ),
-        );
+        if (attempt === this.retryAttempts) throw new StabilizeError(`Query failed: ${(error as Error).message}`, "QUERY_ERROR");
+        await new Promise(res => setTimeout(res, this.retryDelay * Math.pow(2, attempt - 1) + this.getJitter()));
       }
     }
     throw new StabilizeError("Query failed: no attempts made", "QUERY_ERROR");
   }
 
-  async transaction<T>(callback: () => Promise<T>): Promise<T> {
-    if (this.client instanceof Database) {
-      const start = Date.now();
-      this.logger.logDebug("Starting native SQLite transaction");
-
-      const tx = this.client.transaction(async () => {
-        return callback();
-      });
+  /**
+   * Executes a series of database operations within a single atomic transaction.
+   * If any operation in the callback fails, the entire transaction is rolled back.
+   * @template T The return type of the callback function.
+   * @param callback An async function that receives a transactional `DBClient` instance.
+   * @returns A promise that resolves with the result of the callback.
+   * @example
+   * ```
+   * await dbClient.transaction(async (txClient) => {
+   *   await txClient.query('UPDATE accounts SET balance = balance - 100 WHERE id = 1');
+   *   await txClient.query('UPDATE accounts SET balance = balance + 100 WHERE id = 2');
+   * });
+   * ```
+   */
+  async transaction<T>(callback: (txClient: DBClient) => Promise<T>): Promise<T> {
+    if (this.isTransactionClient) return callback(this);
 
-      try {
-        const result = await tx();
-        this.logger.logDebug(
-          `Native transaction committed in ${Date.now() - start}ms`,
-        );
-        return result;
-      } catch (error) {
-        this.logger.logError(error as Error);
-        throw new StabilizeError(
-          `Native transaction failed: ${(error as Error).message}`,
-          "TX_ERROR",
-        );
-      }
+    if (this.client instanceof Database) {
+      const tx = this.client.transaction(() => callback(this));
+      return tx();
+    }
+    
+    if (isMySQLPool(this.client)) {
+        const connection = await this.client.getConnection();
+        const txClient = new DBClient(this.config, this.logger, connection);
+        this.logger.logDebug("Starting MySQL transaction.");
+        try {
+            await txClient.query("START TRANSACTION");
+            const result = await callback(txClient);
+            await txClient.query("COMMIT");
+            return result;
+        } catch (error) {
+            await txClient.query("ROLLBACK");
+            throw error;
+        } finally {
+            connection.release();
+            this.logger.logDebug("MySQL transaction connection released.");
+        }
     }
 
-    const start = Date.now();
-    this.logger.logDebug("Starting manual transaction (non-SQLite)");
-    for (let attempt = 1; attempt <= this.retryAttempts; attempt++) {
+    if (this.client instanceof Pool) {
+      const connection = await this.client.connect();
+      const txClient = new DBClient(this.config, this.logger, connection);
+      this.logger.logDebug("Starting Postgres transaction.");
       try {
-          await this.query("BEGIN", []);
-        const result = await callback();
-        await this.query("COMMIT", []);
-        this.logger.logDebug(
-          `Manual transaction committed in ${Date.now() - start}ms`,
-        );
+        await txClient.query("BEGIN");
+        const result = await callback(txClient);
+        await txClient.query("COMMIT");
         return result;
       } catch (error) {
-        await this.query("ROLLBACK", []).catch(() => {
-          this.logger.logDebug("Rollback failed. Connection may be invalid.");
-        });
-        this.logger.logError(error as Error);
-        if (attempt === this.retryAttempts) {
-          throw new StabilizeError(
-            `Manual transaction failed after ${this.retryAttempts} attempts: ${(error as Error).message}`,
-            "TX_ERROR",
-          );
-        }
-        await new Promise((resolve) =>
-          setTimeout(
-            resolve,
-            this.retryDelay * Math.pow(2, attempt - 1) + this.getJitter(),
-          ),
-        );
+        await txClient.query("ROLLBACK");
+        throw error;
+      } finally {
+        connection.release();
+        this.logger.logDebug("Postgres transaction connection released.");
       }
     }
-    throw new StabilizeError(
-      "Transaction failed: no attempts made",
-      "TX_ERROR",
-    );
-  }
 
-  async savepoint<T>(name: string, callback: () => Promise<T>): Promise<T> {
-    const start = Date.now();
-    this.logger.logDebug(`Starting savepoint ${name}`);
-    await this.query(`SAVEPOINT ${name}`, []);
-    try {
-      const result = await callback();
-      await this.query(`RELEASE SAVEPOINT ${name}`, []);
-      this.logger.logDebug(
-        `Savepoint ${name} released in ${Date.now() - start}ms`,
-      );
-      return result;
-    } catch (error) {
-      await this.query(`ROLLBACK TO SAVEPOINT ${name}`, []).catch(() => {
-        this.logger.logDebug(
-          `Rollback to savepoint ${name} failed. Connection may be invalid.`,
-        );
-      });
-      this.logger.logError(error as Error);
-      throw error;
-    }
+    throw new StabilizeError("Transaction not supported by this client configuration.", "TX_ERROR");
   }
 
+  /**
+   * Closes the database connection pool gracefully.
+   * Should be called when the application is shutting down.
+   */
   async close() {
-    this.preparedStatements.clear();
-      if (this.client instanceof Database) {
+    if (this.client instanceof Database) {
       this.client.close();
-      this.client = null;
-    } else if (
-      this.client &&
-      typeof (this.client as any).close === "function"
-    ) {
-      await (this.client as any).close();
-      this.client = null;
+    } else if (this.client && 'end' in this.client) {
+      await (this.client as any).end();
     }
+    this.client = null!;
     this.logger.logInfo("Database connection closed");
   }
-}
+}

package/decorators.ts

@@ -1,26 +1,61 @@
+/**
+ * @file decorators.ts
+ * @description Contains all the decorators used by the Stabilize ORM.
+ * @author ElectronSz
+ */
+
 import "reflect-metadata";
-import { RelationType } from "./types";
+import { RelationType, DataTypes } from "./types";
+
 
 export const ModelKey = Symbol("model");
 export const ColumnKey = Symbol("column");
 export const ValidatorKey = Symbol("validator");
 export const RelationKey = Symbol("relation");
 export const SoftDeleteKey = Symbol("softDelete");
+export const DefaultKey = Symbol("default");
+export const IndexKey = Symbol("index");
+
+
+export interface ColumnOptions {
+  name?: string;
+  type: DataTypes;
+  length?: number;
+  precision?: number;
+  scale?: number;
+}
 
+/**
+ * Decorator to mark a class as a database model.
+ * @param tableName The name of the table in the database.
+ */
 export function Model(tableName: string) {
   return function (constructor: Function) {
     Reflect.defineMetadata(ModelKey, tableName, constructor);
   };
 }
 
-export function Column(name: string, type: string) {
+/**
+ * Decorator to mark a property as a database column.
+ * @param options The configuration for the column, including name, type, and length.
+ */
+export function Column(options: ColumnOptions | DataTypes) {
   return function (target: any, propertyKey: string) {
     const columns = Reflect.getMetadata(ColumnKey, target) || {};
-    columns[propertyKey] = { name, type };
+ 
+    const columnOptions: ColumnOptions = typeof options === 'object' ? options : { type: options };
+    
+    columns[propertyKey] = {
+      name: columnOptions.name || propertyKey, 
+      ...columnOptions,
+    };
     Reflect.defineMetadata(ColumnKey, columns, target);
   };
 }
 
+/**
+ * Decorator to enforce a NOT NULL constraint on a column.
+ */
 export function Required() {
   return function (target: any, propertyKey: string) {
     const validators = Reflect.getMetadata(ValidatorKey, target) || {};
@@ -29,6 +64,9 @@ export function Required() {
   };
 }
 
+/**
+ * Decorator to enforce a UNIQUE constraint on a column.
+ */
 export function Unique() {
   return function (target: any, propertyKey: string) {
     const validators = Reflect.getMetadata(ValidatorKey, target) || {};
@@ -37,12 +75,40 @@ export function Unique() {
   };
 }
 
+/**
+ * Decorator to set a default value for a column.
+ * @param value The default value.
+ */
+export function Default(value: any) {
+    return function (target: any, propertyKey: string) {
+        Reflect.defineMetadata(DefaultKey, value, target, propertyKey);
+    };
+}
+
+/**
+ * Decorator to create a non-unique index on a column for performance.
+ * @param indexName Optional: A custom name for the index.
+ */
+export function Index(indexName?: string) {
+    return function (target: any, propertyKey: string) {
+        const indexes = Reflect.getMetadata(IndexKey, target) || {};
+        indexes[propertyKey] = indexName || `idx_${propertyKey}`;
+        Reflect.defineMetadata(IndexKey, indexes, target);
+    };
+}
+
+
+/**
+ * Decorator to enable soft-delete functionality on a model.
+ * The decorated property will store the deletion timestamp.
+ */
 export function SoftDelete() {
   return function (target: any, propertyKey: string) {
     Reflect.defineMetadata(SoftDeleteKey, propertyKey, target);
   };
 }
 
+
 export function OneToOne(model: () => any, foreignKey: string) {
   return function (target: any, propertyKey: string) {
     const relations = Reflect.getMetadata(RelationKey, target) || {};
@@ -96,4 +162,4 @@ export function ManyToMany(
     };
     Reflect.defineMetadata(RelationKey, relations, target);
   };
-}
+}