stabilize-orm 1.1.6 → 1.1.8

package/bun.lock

@@ -7,6 +7,7 @@
         "@types/pg": "^8.15.5",
         "@types/uuid": "^11.0.0",
         "commander": "^12.1.0",
+        "dotenv": "^17.2.3",
         "figlet": "^1.9.3",
         "glob": "^11.0.0",
         "ioredis": "^5.4.1",
@@ -306,6 +307,8 @@
 
     "denque": ["denque@2.1.0", "", {}, "sha512-HVQE3AAb/pxF8fQAoiqpvg9i3evqug3hoiwakOyZAwJm+6vZehbkYXZ0l4JxS+I3QxM97v5aaRNhj8v5oBhekw=="],
 
+    "dotenv": ["dotenv@17.2.3", "", {}, "sha512-JVUnt+DUIzu87TABbhPmNfVdBDt18BLOWjMUFJMSi/Qqg7NTYtabbvSNJGOJ7afbRuv9D/lngizHtP7QyLQ+9w=="],
+
     "eastasianwidth": ["eastasianwidth@0.2.0", "", {}, "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA=="],
 
     "emoji-regex": ["emoji-regex@9.2.2", "", {}, "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg=="],

package/client.ts

@@ -37,7 +37,7 @@ function isMySQLPool(client: any): client is mysql.Pool {
 export class DBClient {
   private client!: Database | Pool | mysql.Pool | PoolClient | mysql.PoolConnection;
   private logger: Logger;
-  public readonly config: DBConfig; 
+  public readonly config: DBConfig;
   private retryAttempts: number;
   private retryDelay: number;
   private maxJitter: number;
@@ -82,12 +82,12 @@ export class DBClient {
     } 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 });
+    } else if (config.type = DBType.Postgres) {
+      this.client = new Pool({ connectionString: config.connectionString! });
       this.logger.logDebug(`Initialized Postgres Pool client.`);
     }
   }
-  
+
   /** @internal Gets a random jitter value to add to retry delays. */
   private getJitter = () => Math.random() * this.maxJitter;
 
@@ -103,14 +103,17 @@ export class DBClient {
    * 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);
 
     for (let attempt = 1; attempt <= this.retryAttempts; attempt++) {
       try {
         let result: any;
 
+        // Log the query before execution
+        this.logger.logQuery(query, params);
+
         if (this.client instanceof Database) { // SQLite
           let stmt = this.preparedStatements.get(query);
           if (!stmt) {
@@ -118,25 +121,34 @@ export class DBClient {
             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}`);
+        } else if (this.config.type === DBType.MySQL && isMySQLPool(this.client)) { // MySQL
+          const [rows] = await (this.client as mysql.Pool).query(query, params);
+          result = rows;
+        } else if (this.config.type === DBType.Postgres ) { // Postgres
+
+          let paramIndex = 0;
+          const pgQuery = query.replace(/\?/g, () => `$${++paramIndex}`);
           const pgResult = await (this.client as Pool).query(pgQuery, params);
-          result = pgResult.rows;
+          result = Array.isArray(pgResult.rows) ? pgResult.rows : [];
+        } else {
+          throw new StabilizeError("Unknown database client type", "QUERY_ERROR");
         }
 
         const executionTime = Date.now() - start;
         this.logger.logQuery(query, params, executionTime);
-        return result as T[];
+        return Array.isArray(result) ? result as T[] : [];
       } catch (error) {
+        console.log("error: ", error);
+
         this.logger.logError(error as Error);
-        if (attempt === this.retryAttempts) throw new StabilizeError(`Query failed: ${(error as Error).message}`, "QUERY_ERROR");
+        if (attempt === this.retryAttempts) {
+          throw new StabilizeError(`Query failed after ${this.retryAttempts} attempts: ${(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");
+    // This line should theoretically be unreachable if retryAttempts >= 1
+    throw new StabilizeError("Query failed: maximum retries reached without success", "QUERY_ERROR");
   }
 
   /**
@@ -160,23 +172,23 @@ export class DBClient {
       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 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.");
+      }
     }
 
     if (this.client instanceof Pool) {
@@ -184,12 +196,12 @@ export class DBClient {
       const txClient = new DBClient(this.config, this.logger, connection);
       this.logger.logDebug("Starting Postgres transaction.");
       try {
-        await txClient.query("BEGIN");
+        await txClient.migrationQuery("BEGIN");
         const result = await callback(txClient);
-        await txClient.query("COMMIT");
+        await txClient.migrationQuery("COMMIT");
         return result;
       } catch (error) {
-        await txClient.query("ROLLBACK");
+        await txClient.migrationQuery("ROLLBACK");
         throw error;
       } finally {
         connection.release();
@@ -213,4 +225,46 @@ export class DBClient {
     this.client = null!;
     this.logger.logInfo("Database connection closed");
   }
+
+  /**
+  * Executes a SQL query for migrations/transactions that
+  * does NOT expect any result rows and returns void.
+  * This is used for DDL and transaction statements (e.g. CREATE TABLE, BEGIN, COMMIT)
+  * that should never be iterated over.
+  *
+  * Logs the execution time for each query.
+  *
+  * @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 when the query has executed.
+  * @example
+  * ```
+  * await dbClient.migrationQuery('CREATE TABLE ...');
+  * await dbClient.migrationQuery('BEGIN');
+  * await dbClient.migrationQuery('COMMIT');
+  * ```
+  */
+  async migrationQuery(query: string, params: any[] = []): Promise<void> {
+    const start = Date.now();
+    this.logger.logQuery(query, params);
+
+    if (this.client instanceof Database) { // SQLite
+      let stmt = this.preparedStatements.get(query);
+      if (!stmt) {
+        stmt = this.client.prepare(query);
+        this.preparedStatements.set(query, stmt);
+      }
+      stmt.run(...params);
+    } else if (isMySQLPool(this.client) || ('query' in this.client && 'release' in this.client && !(this.client instanceof Pool))) { // mysql2 Pool or Connection
+      await (this.client as mysql.Pool).query(query, params);
+    } else if (this.config.type = DBType.Postgres) { // Postgres Pool or Client
+      let paramIndex = 0;
+      const pgQuery = query.replace(/\?/g, () => `$${++paramIndex}`);
+      await (this.client as Pool).query(pgQuery, params);
+    }
+
+    const executionTime = Date.now() - start;
+    this.logger.logQuery(query, params, executionTime);
+  }
+
 }

package/index.ts

@@ -2,7 +2,6 @@
  * @file stabilize.ts
  * @description The main entry point for the Stabilize ORM, tying together the client, cache, and repositories.
  * @author ElectronSz
- * @date 2025-10-15 20:35:34
  */
 import { Cache } from "./cache";
 import { DBClient } from "./client";

package/migrations.ts

@@ -7,7 +7,7 @@
 
 import { DBClient } from "./client";
 import { ModelKey, ColumnKey, ValidatorKey, SoftDeleteKey } from "./decorators";
-import { type DBConfig, type Migration, StabilizeError, DBType } from "./types";
+import { type DBConfig, type Migration, StabilizeError, DBType, DataTypes } from "./types";
 
 type ColumnData = { name: string; type: string };
 type ColumnMetadata = Record<string, ColumnData>;
@@ -30,6 +30,87 @@ function formatQuery(query: string, dbType: DBType): string {
   return query;
 }
 
+
+/**
+ * Maps an abstract data type (from DataTypes enum or a string) to the correct SQL type string
+ * for the specified database dialect (Postgres, MySQL, or SQLite).
+ *
+ * This function enables model definitions to be portable across different databases by
+ * converting each logical type to its proper SQL type in CREATE TABLE migrations.
+ *
+ * @param dt - The data type to map. Accepts either a value from the DataTypes enum, or a string
+ *             (e.g., "string", "integer", "boolean", etc.).
+ * @param dbType - The target database dialect (DBType.Postgres, DBType.MySQL, or DBType.SQLite).
+ * @returns The SQL column type string appropriate for the database and logical type.
+ *
+ */
+function mapDataTypeToSql(dt: DataTypes | string, dbType: DBType): string {
+  let type: string;
+  if (typeof dt === "string") {
+    type = dt.toLowerCase();
+  } else {
+    type = DataTypes[dt].toLowerCase();
+  }
+
+  if (dbType === DBType.Postgres) {
+    switch (type) {
+      case "string": return "TEXT";
+      case "text": return "TEXT";
+      case "integer": return "INTEGER";
+      case "bigint": return "BIGINT";
+      case "float": return "REAL";
+      case "double": return "DOUBLE PRECISION";
+      case "decimal": return "DECIMAL";
+      case "boolean": return "BOOLEAN";
+      case "date": return "DATE";
+      case "datetime": return "TIMESTAMP";
+      case "json": return "JSONB";
+      case "uuid": return "UUID";
+      case "blob": return "BYTEA";
+      default: return "TEXT";
+    }
+  }
+  if (dbType === DBType.MySQL) {
+    switch (type) {
+      case "string": return "VARCHAR(255)";
+      case "text": return "TEXT";
+      case "integer": return "INT";
+      case "bigint": return "BIGINT";
+      case "float": return "FLOAT";
+      case "double": return "DOUBLE";
+      case "decimal": return "DECIMAL(10,2)";
+      case "boolean": return "TINYINT(1)";
+      case "date": return "DATE";
+      case "datetime": return "DATETIME";
+      case "json": return "JSON";
+      case "uuid": return "CHAR(36)";
+      case "blob": return "BLOB";
+      default: return "TEXT";
+    }
+  }
+  // SQLite
+  if (dbType === DBType.SQLite) {
+    switch (type) {
+      case "string": return "TEXT";
+      case "text": return "TEXT";
+      case "integer": return "INTEGER";
+      case "bigint": return "INTEGER";
+      case "float": return "REAL";
+      case "double": return "REAL";
+      case "decimal": return "NUMERIC";
+      case "boolean": return "INTEGER";
+      case "date": return "TEXT";
+      case "datetime": return "TEXT";
+      case "json": return "TEXT";
+      case "uuid": return "TEXT";
+      case "blob": return "BLOB";
+      default: return "TEXT";
+    }
+  }
+  return "TEXT";
+}
+
+
 /**
  * @internal
  * Gets the database-specific SQL for an auto-incrementing primary key.
@@ -62,7 +143,7 @@ function getTimestampType(dbType: DBType): string {
       return "DATETIME";
     case DBType.SQLite:
     default:
-      return "TEXT"; 
+      return "TEXT";
   }
 }
 
@@ -95,8 +176,8 @@ function getTimestampDefault(dbType: DBType): string {
  */
 export async function generateMigration(
   model: new (...args: any[]) => any,
-  name: string, 
-  dbType: DBType = DBType.Postgres,
+  name: string,
+  dbType: DBType,
 ): Promise<Migration> {
   const tableName = Reflect.getMetadata(ModelKey, model);
   if (!tableName) {
@@ -105,19 +186,18 @@ export async function generateMigration(
 
   const columns: ColumnMetadata = Reflect.getMetadata(ColumnKey, model.prototype) || {};
   const validators: ValidatorMetadata = Reflect.getMetadata(ValidatorKey, model.prototype) || {};
-  const softDeleteField = Reflect.getMetadata(SoftDeleteKey, model.prototype);
 
-  const columnDefs = Object.entries(columns).map(([key, col]) => {
-    if (col.name === "id") {
-      return `id ${getAutoIncrementPK(dbType)}`;
-    }
+  const columnDefs: string[] = [];
+
+  for (const [key, col] of Object.entries(columns)) {
+    const defParts: string[] = [];
 
-    const defParts: string[] = [col.name];
-    
-    if (["createdAt", "updatedAt"].includes(key) || (softDeleteField && key === softDeleteField)) {
-      defParts.push(getTimestampType(dbType));
+    if (col.name === "id") {
+      defParts.push("id");
+      defParts.push(getAutoIncrementPK(dbType));
     } else {
-      defParts.push(col.type);
+      defParts.push(col.name);
+      defParts.push(mapDataTypeToSql(col.type, dbType));
     }
 
     if (validators[key]?.includes("required")) {
@@ -127,21 +207,13 @@ export async function generateMigration(
       defParts.push("UNIQUE");
     }
 
-    if (key === "createdAt") {
-      defParts.push(getTimestampDefault(dbType));
-    }
-
-    return defParts.join(" ");
-  });
-
-  if (softDeleteField && !columns[softDeleteField]) {
-    columnDefs.push(`${softDeleteField} ${getTimestampType(dbType)}`);
+    columnDefs.push(defParts.join(" "));
   }
 
   const up = [`CREATE TABLE IF NOT EXISTS ${tableName} (${columnDefs.join(", ")})`];
   const down = [`DROP TABLE IF EXISTS ${tableName}`];
 
-  return { up, down, name: tableName }; 
+  return { up, down, name };
 }
 
 /**
@@ -153,20 +225,20 @@ export async function generateMigration(
 function getMigrationsTableSQL(dbType: DBType): string {
   switch (dbType) {
     case DBType.Postgres:
-      return `CREATE TABLE IF NOT EXISTS migrations (
+      return `CREATE TABLE IF NOT EXISTS stabilize_migrations (
         id SERIAL PRIMARY KEY,
         name VARCHAR(255) UNIQUE NOT NULL,
         applied_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
       )`;
     case DBType.MySQL:
-      return `CREATE TABLE IF NOT EXISTS migrations (
+      return `CREATE TABLE IF NOT EXISTS stabilize_migrations (
         id INT AUTO_INCREMENT PRIMARY KEY,
         name VARCHAR(255) UNIQUE NOT NULL,
         applied_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
       )`;
     case DBType.SQLite:
     default:
-      return `CREATE TABLE IF NOT EXISTS migrations (
+      return `CREATE TABLE IF NOT EXISTS stabilize_migrations (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         name TEXT UNIQUE NOT NULL,
         applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
@@ -190,8 +262,8 @@ export async function runMigrations(config: DBConfig, migrations: Migration[]) {
 
     for (const [index, migration] of migrations.entries()) {
       const name = migration.name || `migration_${index}_${new Date().getTime()}`;
-      
-      const selectQuery = formatQuery(`SELECT id FROM migrations WHERE name = ?`, dbType);
+
+      const selectQuery = formatQuery(`SELECT id FROM stabilize_migrations WHERE name = ?`, dbType);
       const applied = await client.query<{ id: number }>(selectQuery, [name]);
 
       if (applied.length === 0) {
@@ -200,17 +272,17 @@ export async function runMigrations(config: DBConfig, migrations: Migration[]) {
           for (const query of migration.up) {
             await txClient.query(query);
           }
-          
-          const insertQuery = formatQuery(`INSERT INTO migrations (name, applied_at) VALUES (?, ?)`, dbType);
+
+          const insertQuery = formatQuery(`INSERT INTO stabilize_migrations (name, applied_at) VALUES (?, ?)`, dbType);
           await txClient.query(insertQuery, [name, new Date().toISOString()]);
-          
+
           console.log(`Migration ${name} applied successfully.`);
         });
       }
     }
   } catch (error) {
     console.error("Migration failed:", error);
-    throw error; 
+    throw error;
   } finally {
     await client.close();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stabilize-orm",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "description": "A lightweight, type-safe ORM for Bun.js with support for SQLite, MySQL, PostgreSQL, and Redis caching",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/repository.ts

@@ -227,7 +227,7 @@ export class Repository<T> {
     );
     return result;
   }
-  
+
   /**
    * Creates multiple records in the database in batches.
    * @param entities An array of entities to create.
@@ -275,47 +275,72 @@ export class Repository<T> {
       const batch = entities.slice(i, i + batchSize);
       const keys = Object.keys(batch[0]!).filter((k) => this.columns[k]);
       const columnNames = keys.map((k) => this.columns[k]?.name).join(", ");
-      const placeholders = `(${keys.map(() => "?").join(", ")})`;
-      let query = `INSERT INTO ${this.table} (${columnNames}) VALUES ${batch.map(() => placeholders).join(", ")}`;
-      const params = batch.flatMap((entity) =>
+
+      let query: string;
+      let params: any[] = batch.flatMap((entity) =>
         keys.map((k) => (entity as any)[k]),
       );
 
-      let batchResults: T[] = [];
-      let ids: (number | string)[] = [];
-
       if (dbType === DBType.Postgres) {
-        query += " RETURNING *";
-        batchResults = await client.query<T>(query, params);
-        ids = batchResults.map((r) => (r as any).id);
+        // PostgreSQL: numbered placeholders ($1, $2, ...)
+        let paramIdx = 1;
+        const valuePlaceholders = batch
+          .map(
+            () =>
+              `(${keys.map(() => `$${paramIdx++}`).join(", ")})`
+          )
+          .join(", ");
+        query = `INSERT INTO ${this.table} (${columnNames}) VALUES ${valuePlaceholders} RETURNING *`;
+        const batchResults = await client.query<T>(query, params);
+        const ids = batchResults.map((r) => (r as any).id);
+
+        // Handle relation loading if needed
+        let finalResults = batchResults;
+        if (ids.length > 0 && batchResults.length === 0) {
+          const queryBuilder = this.find().where(
+            `id IN (${ids.map(() => "?").join(", ")})`,
+            ...ids,
+          );
+          if (options.relations) {
+            for (const rel of options.relations) {
+              await this.loadRelation(queryBuilder, rel);
+            }
+          }
+          finalResults = await queryBuilder.execute(client);
+        }
+        results.push(...finalResults);
+
       } else {
+        // SQLite/MySQL: ? placeholders
+        const placeholders = `(${keys.map(() => "?").join(", ")})`;
+        query = `INSERT INTO ${this.table} (${columnNames}) VALUES ${batch.map(() => placeholders).join(", ")}`;
         await client.query(query, params);
-        ids = (
+        const ids = (
           await client.query<{ id: number }>(
             `SELECT id FROM ${this.table} ORDER BY id DESC LIMIT ?`,
             [batch.length],
           )
         ).map((row) => row.id);
-      }
 
-      if (ids.length > 0 && batchResults.length === 0) {
-        const queryBuilder = this.find().where(
-          `id IN (${ids.map(() => "?").join(", ")})`,
-          ...ids,
-        );
-        if (options.relations) {
-          for (const rel of options.relations) {
-            await this.loadRelation(queryBuilder, rel);
+        let batchResults: T[] = [];
+        if (ids.length > 0) {
+          const queryBuilder = this.find().where(
+            `id IN (${ids.map(() => "?").join(", ")})`,
+            ...ids,
+          );
+          if (options.relations) {
+            for (const rel of options.relations) {
+              await this.loadRelation(queryBuilder, rel);
+            }
           }
+          batchResults = await queryBuilder.execute(client);
         }
-        batchResults = await queryBuilder.execute(client);
+        results.push(...batchResults);
       }
-
-      results.push(...batchResults);
     }
-    
+
     if (this.cache) await this.cache.invalidatePattern(`find:${this.table}:*`);
-    
+
     this.logger.logDebug(
       `Bulk created ${results.length} ${this.table} entities in ${(performance.now() - start).toFixed(2)}ms`,
     );
@@ -495,7 +520,7 @@ export class Repository<T> {
     let id: number | string | undefined = (results[0] as any)?.id || (entity as any).id;
 
     if (!id && dbType !== DBType.Postgres) {
-       if (dbType === DBType.SQLite) {
+      if (dbType === DBType.SQLite) {
         id = (await client.query<{ id: number }>("SELECT last_insert_rowid() as id"))[0]?.id;
       } else if (dbType === DBType.MySQL) {
         const result = await client.query<{ "LAST_INSERT_ID()": number }>("SELECT LAST_INSERT_ID()");
@@ -513,7 +538,7 @@ export class Repository<T> {
         await this.cache.set(`findOne:${this.table}:${id}`, [result], 60);
       }
     }
-    
+
     this.logger.logDebug(
       `Upserted ${this.table} with ID ${id} in ${(performance.now() - start).toFixed(2)}ms`,
     );
@@ -545,7 +570,7 @@ export class Repository<T> {
       ? `UPDATE ${this.table} SET ${this.softDeleteField} = ? WHERE id = ?`
       : `DELETE FROM ${this.table} WHERE id = ?`;
     const params = this.softDeleteField ? [new Date().toISOString(), id] : [id];
-    
+
     await client.query(query, params);
 
     if (this.cache) {
@@ -638,7 +663,7 @@ export class Repository<T> {
         "RECOVER_ERROR",
       );
     }
-    
+
     await client.query(
       `UPDATE ${this.table} SET ${this.softDeleteField} = NULL WHERE id = ?`,
       [id],
@@ -653,7 +678,7 @@ export class Repository<T> {
         `findOne:${this.table}:${id}`,
       ]);
     }
-    
+
     this.logger.logDebug(
       `Recovered ${this.table} with ID ${id} in ${(performance.now() - start).toFixed(2)}ms`,
     );